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PREFACE 



The purpose of this manual is to introduce the Multics environment to 
applications programmers who have experience on another operating system but are 
new to Multics. 

It is very important that you understand exactly who this manual is for, 
and what assumptions this manual makes about its audience, before you begin to 
use it. 

The intended audience of this manual is applications programmers. It is 
assumed that you have programmed on some other system(s) and that you have some 
basic knowledge of at least one higher level language (COBOL, FORTRAN, PL/I, 
etc.). No attempt is made here to teach you how to program. This manual is 
only intended to show you how to do the things you know how to do on another 
system on Multics . 

As an applications programmer, you look at an operating system from the 
viewpoint of some programming language. This manual does not attempt to discuss 
the use of any particular language on Multics, but rather, concerns itself with 
those practices which are appropriate no matter which language you use. For 
information on specific languages you should refer to the Language Users 1 
Guides. The names of these guides are included in the list of useful manuals 
for new programmers given at the end of this preface. 

This manual assumes that you are registered on Multics, and that you know 
how to log in and use a terminal. It also assumes that you have some general 
familiarity with the fundamental concepts and facilities of the Multics system. 
This information is available in the following publications: 

New Users 1 Introduction to Multics - Part I Order No. CH24 

New Users * Introduction to Multics - Part Tl Order No. CH25 

You should feel comfortable with the use of segments, directories, text 
editors, access control, commands, and active functions. If you don't, you 
should review the manuals listed above, as no review of this material will be 
presented here. 



The information and specifications in this document are 
subject to change without notice. This document contains 
information about Honeywell products or services that may 
not be available outside the United States. Consult your 
Honeywell Marketing Representative. 
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Section 1 of this manual offers an overview of the Multies operating system 
in general terms, to give you some idea of why programming on Multies may be 
different from working on other systems. 



Section 2 offers a step-by-step approach to the essentials of programming 
on Multies. It shows you how to create, compile, execute, revise, and document 
your programs in this environment, how to manipulate your segments, and how to 
create storage system links. Sample terminal sessions are also included. 



Section 3 takes you one step further by showing you the uses of dynamic 
linking on Multies. 



Section 4 provides you with an introduction to Multies input/output 
processing, showing you how to use the terminal for I/O and how to begin using 
I/O commands. 



Section 5 discusses the use of a Multies debugging tool. 



Section 6 discusses the use of a Multies performance measurement tool. 



Section 7 explains the Multies absentee facility, which offers capabilities 
similar to batch processing on other systems. 



Section 8 offers a reference to all of the Multies commands by function, 
including a brief description of each command. 



The appendixes of this manual contain material which is specific to a 
particular language, somewhat advanced, or useful only to certain users. 



Appendix A shows you how to use Multies to best advantage in PL/I 
programming. 



Appendix B offers a step-by-step explanation of a PL/I text editor program. 
(This is for people who are ready to begin systems programming work.) 



Appendix C briefly introduces you to various Multies subsystems. 



Appendix D shows you how to use the Edm text editor. 

The information presented here is a subset of that contained in the primary 
Multies reference document, the Multies Programmers' Manual (MPM). The MPM 
should be used as a reference to Multies once you have become familiar with the 
concepts covered in this introductory guide. The MPM consists of the following 
individual manuals: 



Reference Guide 


Order 


No. 


AG91 


Commands and Active Functions 


Order 


No. 


AG92 


Subroutines 


Order 


No. 


AG93 


Subsystem Writers 1 Guide 


Order 


No. 


AK92 


Peripheral Input/Output 


Order 


No. 


AX49 


Communications Input/Output 


Order 


No. 


CC92 
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Throughout this manual, references are made to the MPM Reference Guide , the 
MPM Commands and Active Functions , the MPM Subroutines , and the MPM Subsystem 
Writers ' Guide manuals. For convenience, these references are as follows: 



MPM Reference Guide 

MPM Commands 

MPM Subroutines 

MPM Subsystem Writers' Guide 



Other Multics manuals of interest to new programmers are listed below. 



• Languages: 



Multics 


APL 


Order 


No. 


AK95 


Multics 


Basic 


Order 


No. 


AM82 


Multics 


COBOL Users 1 Guide 


Order 


No. 


AS43 


Multics 


COBOL Reference Manual 


Order 


No. 


AS44 


Multics 


FORTRAN Users 1 Guide 


Order 


No. 


CC70 


Multics 


FORTRAN Reference Manual 


Order 


No. 


AT58 


Multics 


PL/I Language Specification 


Order 


No. 


AG94 


Multics 


PL/I Reference Manual 


Order 


No. 


AM83 


Subsystems: 








Multics 


FAST Subsystem Users 1 Guide 


Order 


No. 


AU25 


Multics 


GCOS Environment Simulator 


Order 


No. 


AN05 


Multics 


Graphics System 


Order 


No. 


AS40 


Logical Inquiry and Update System 
Reference Manual 


Order 


No. 


AZ49 


Multics 


Relational Data Store (MRDS) 








Reference Manual 


Order 


No. 


AW53 


Multics Report Program Generator 








Reference Manual 


Order 


No. 


CC69 


Multics 


Sort/Merge 


Order 


No. 


AW 32 


WORDPRO 


Reference Guide 


Order 


No. 


AZ98 


Micellaneous: 








Multics 


Pocket Guide - Commands 








and Active Functions 


Order 


No. 


AW17 


Index to Multics Manuals 


Order 


No. 


AN50 



The Multics operating system is referred to in this manual as either 
"Multics" or "the system". The Emacs, Qedx, Ted, and Edm text editors are 
referred to as "Emacs", "Qedx", "Ted", and "Edm" respectively. 
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SECTION 1 



THE MULTICS APPROACH 



The Multics approach is quite different from that of a traditional batch 
operating system. The intent of this section is to show you how Multics is 
different, by giving you a general overview of the system* s "personality", then 
describing in more detail three of its major characteristics: segmented virtual 
memory, dynamic linking, and controlled sharing and security. As these 
characteristics are discussed, important concepts associated with each will be 
introduced and explained. Familiarity with these concepts will help you when 
you read later sections of this manual and begin to program on Multics. 



Multics is a large, powerful, well-established system, which is constantly 
being refined, and provides a wide range of commands, languages, and subsystems. 
Despite its size and complexity, Multics is easy to learn and use. It has been 
designed to serve a wide variety and number of users, all cooperating and sharing 
resources. Multics offers its users the following advantages: 

• support for online usage: Multics has been designed to support online 
processing as well as batch processing. You can accomplish all of 
your programming tasks as either an interactive (online) user or an 
absentee (batch) user. Applications, debugging tools, data base 
management facilities, administrative tools and utilities are all 
accessible online. In one terminal session, you can write, compile, 
execute and debug your program. (See "Sample Terminal Sessions" in 
Section 2, and "Probe" in Section 5.) 

• consistent user interface: A great deal of thought has gone into 
making similar parts of Multics work in similar ways. For example, 
common control arguments such as -all and -brief are used with many 
different commands, and in each case, the control argument performs a 
similar function. In addition, all parts of the system have been 
designed to work together. 

• uniformity of control language: Batch processing on Multics is supported 
by the absentee facility (described in Section 7). An absentee job is 
processed like an interactive terminal session; it's directed by the 
same language as that used for interactive jobs. In other words, no 
special job control language (JCL) is ever required on Multics. The 
system commands and routines provide the logical branching, conditional 
execution, input/output control, and file system specifications necessary 
to direct any job. 

• ease of use: On Multics, users are not asked to give information or 
make decisions ahead of time. There are many examples of this. You 
don't have to know or specify either a segment's size or its location 
to use it. You don't have to make your need for tape drives and 
similar resources known in advance. Intelligent defaults mean that 
you need not create a correspondence between a file and an I/O name. 
Dynamic linking (described later in this section) means that you need 
not name or prefetch programs you want to execute. You can set up a 
tempora'ry working array for your PL/I or FORTRAN program in its own 
segment, without specifying how much space you need or worrying that 
the array will get too big. You will find that this lack of required 
prespecif ication greatly simplifies your use of the system. 
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SEGMENTED VIRTUAL MEMORY 



The most significant difference between the Multics programming environment 
and that of most other contemporary computer programming systems lies in its 
approach to addressing online storage. Most computer systems have two sharply 
distinct environments: a resident file storage system in which programs are 
created, and translated programs and data are stored; and an execution environment 
consisting of a processor and a "core image", which contains the instructions 
and data for the processor. Supervisor procedures provide subroutines for physically 
moving copies of programs and data back and forth between the two environments. 



In Multics, there is one conceptual memory, which is known as the virtual 
memory . The traditional distinction between secondary storage and main memory 
has no meaning, because a single infinitely large memory is simulated by the 
software, with data stored in finite segments which appear to be in memory at 
all times. Figure 1-1 illustrates this difference between a traditional system 
and the Multics virtual memory. 



With the line between the two traditional environments deliberately blurred, 
program construction on Multics is simplified: most programs need only be cognizant 
of one environment instead of two. This blending of the two environments is 
accomplished by extending the processor/core image environment. In Multics, 
your share of the processor is termed a process , and your core image is abstracted 
into what is called an address space . In a sense, each segment is a core image, 
and your process can have lots of them. 



The easiest way to think about the terms process and address space is to 
imagine your process as a private computer and your address space as a private 
memory for your process to work in. (See "Process, Address Space, and Execution 
Point" next in this section.) 



Another important difference between the Multics environment and that of 
most other systems is that an address in Multics has two parts: a segment 
identifier and a location, or off set , within the segment. 



Traditional Address 



Segment 



Offset 



Multics Address 



(See "Segments and Addressing" later in this section.) 
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Figure 1-1. Traditional System vs. Multics Virtual Memory 
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Process , Address Space , and Execution Point 



When you log in to the system, you are allocated system resources in an 
environment known as a process. A process consists of a collection of segments 
called an address space, over which a single execution point is free to roam 
(i.e., to fetch instructions and make data references). 



A process executes programs on your behalf, either directly in response to 
your instructions or automatically as part of supporting the programs you invoke 
directly. The programs executed on your behalf and the data they reference make 
up your address space, and that address space combined with the action of executing 
those programs make up your process. Your execution point is whatever is executing 
at any moment. 



Space within the virtual memory is dynamically assigned to your address 
space. Its contents are a function of the sequence of instructions that are 
processed between the time you log in and the time you log out, and thus it 
dynamically shrinks and grows as necessary. Your address space is different 
from the usual core image in that it is larger and it is segmented. A segment 
may be of any size from 0 to 255K, and an address space may have a large number 
of segments (typically about 200). Usually, each separately translated program 
resides in a different segment; collections of data which are large enough to be 
worthy of a separate name are placed in a segment by themselves. The system 
assigns attributes (access control and length, for example) to each of these 
segments based on their logical use. There is a distinct address space for each 
user who is logged in, even though many users may share the very same segments 
in their address spaces. 



Your process is created when you log in, and destroyed when you log out, 
when you request a new process with the new_proc command, or when some kinds of 
errors occur. You may view your process as if all system resources are dedicated 
to it alone— as if you have a processor all to yourself—when in reality, all 
resources are being shared among many processes. Not only are there other interactive 
processes running, there are also absentee processes running as "background" to 
the interactive ones, and there are various daemon processes running, which are 
associated with the normal operation of the system and not connected to any 
user. All of these processes are continually cooperating and competing for 
processor time and main storage resources. The processor is multiplexed between 
processes according to rules defined for the system as a whole, with the object 
of sharing resources in an equitable manner. 



Processes can share with each other, and this sharing is of two types. 
First, any references to a segment by more than one process are references to 
the same segment. Second, a large part of the address space in all processes is 
identical, because the parts of the system shared by all users are given segment 
numbers (described below) that are the same for all processes. Figure 1-2 illustrates 
this sharing of segments. 



You should remember that each process's virtual memory is private to it. 
This means that changes made to one process's virtual memory assignments do not 
affect those of other processes. In addition, when a segment is being shared, 
it means that multiple users may not only read the segment, but also write it. 
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Figure 1-2, Processes Sharing a Segment 
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Segments and Addressing 



It's important to understand that 
segment can be addressed directly, like 
written record by record like a file on 
is in a segment: 



a Multics segment is not a file. A 
memory. It doesn't have to be read or 
other systems. On Multics, everything 



program source code 
program object code 
data files 
mail boxes 
work areas 
temporary storage 
exec corns 



There are two main reasons why segments are used in Multics. The first is 
that they make it possible for all your process's programs and data to be easily 
and directly addressable. The second is that they make it possible to protect 
and share programs and data by controlling access at the hardware level. (For 
more on this, see "Controlled Sharing and Security" later in this section.) 



The segment is often described as the basic unit of storage in Multics 
because all locating (addressing) of data in the system is done in terms of 
segments. The physical movement of information between main memory and secondary 
storage is fully automatic in Multics (it is done by the paging mechanism). The 
usual complex combination of file access methods and job control language which 
you are probably used to is replaced by a simple two-dimensional addressing 
scheme. This scheme involves the user-assigned symbolic name of the segment 
(its pathname), and the address of the desired item within the segment. Even 
relative addresses are usually given in symbolic terms through the data description 
facilities of the language you're using. Thus, each segment appears to its user 
as independent memory, symbolically located. Segments don't have to be in specific 
storage locations. They can be relocated anywhere in memory and grow and shrink 
as need be. 
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References to any portion of your address space consist of a segment name 
and a location within the segment; all addresses are interpreted as offsets 
within segments. To increase the efficiency of a storage reference, a segment 
number becomes associated with a segment name when the segment is initiated 
(added to your process's address space). A segment is said to be known to a 
process when it has been uniquely associated with a segment number in that 
process. The segment number is a temporary alias for the segment name, which is 
more easily translated into a storage address by the hardware. When you write: 

<symbolic_name> I [ symbolic__of f set ] 

the hardware uses: 

<segment_number> ! [of f set_number ] 

The association between a segment name and a segment number is retained until 
the segment is terminated (removed from your process ! s address space). If it is 
terminated and initiated again, the number will be different. (See the discussion 
of initiating and terminating segments in Section 3-) Thus, every address or 
pointer is a pair of numbers: the segment number and the offset within the 
segment. This pair of numbers forming an address represents the coordinate of a 
location in the two-dimensional address space. See Figure 1-3 for a graphic 
representation of a two-dimensional address space. See Figure 1-4 for an 
illustration of the life of a segment. 



A program can create a segment by issuing a call to the system specifying 
the symbolic name as an argument. Different users can incorporate the same 
segment into their programs just by specifying its name. (A program need not 
copy a segment to use it.) A program can address any item within a segment 
using "segment, 1" where segment is the symbolic name of the segment and 1 is 
the location of the desired item within the segment. The ALM (Multics assembly 
language) instruction shown below illustrates a symbolic reference to location 
"x" in segment "data": 

Ida data$x 



For more information on the Multics virtual memory, see the MPM Reference 
Guide . 



DYNAMIC LINKING 



Many programs make calls to external subroutines or use external variables. 
On most systems, these external references are resolved during loading or linkage 
editing. When the program is loaded into memory, external subroutines are loaded 
from libraries or user data sets, and storage is allocated for external variables. 
On Multics, external references are resolved when the program runs ; i.e., the 
point at which something is used is the point at which it is found. This means 
that a compiled program on Multics is directly executable. Segmentation is what 
makes this possible - it gives each segment a "zero" location, so no relocation 
is necessary. 



1-7 



AG90-03 



SUPERVISOR 
A 



USER PROGRAMS, DATA, COMMANDS 



256K 



o 

LL1 
CO 

O 
H 

z: 



LU 
CO 



SEGMENTS 



Figure 1-3- Two-Dimensional Address Space 
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Figure 1-4. The Life of a Segment 



Note 1. Events in parentheses are not user visible. 



Note 2. Segments are automatically divided by the hardware into storage units 
known as pages , with a fixed size of 1024 words. (One word is equal 
to 36 bits or 4 9-bit bytes.) 
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Dynamic linking is accomplished by having the compiler leave in the object 
code of a compiled program an indirect word with a "fault tag" which, if used in 
an indirect address reference, causes a linkage fault to the dynamic linker. 
The linker inspects the location causing the fault, and from pointers found 
there, locates the symbolic name of the program being called or the data segment 
being referenced. It then locates the appropriate segment, maps it into the 
current address space, and replaces the indirect word with a new one containing 
the address of the program or data entry point, so that future references will 
not cause a linkage fault. When the system comes across an unresolved reference, 
it uses what are known as search rules (described in Section 3) to find the 
needed segment and establish the necessary link. This process is known as snapping 
a link . To see how the linkage fault caused by the ALM instruction mentioned 
previously would be resolved, refer to Figure 1-5. 



With dynamic linking, you don T t pay the cost of resolving references (for 
example, calls to error routines) unless they are actually needed. If a subroutine 
is never called, it doesn't even have to exist, and the main program will still 
run correctly. An item in the file system has to be in your address space for 
you to use it, but it doesn't have to be copied and brought into memory before 
execution. The virtual memory guarantees that any item you reference is where 
the processor can address it directly. 



Dynamic linking simplifies your programming by totally eliminating the loading 
step. It also eliminates the need for a complicated job control language for 
retrieving, prelinking, and executing programs, and for defining and locating 
input /output files. 



For more information on dynamic linking, see the MPM Reference Guide. 



CONTROLLED SHARING AND SECURITY 



Multics permits controlled sharing of the operating system software and 
libraries, the language compilers, the data bases, and all user code and data. 
You can create links to other programs and data, give and revoke access, directly 
access any information in the system to which you have access, and share a 
single copy in core. 



1-10 



AG90-03 



ALU program 



Ida data$x 



compilation 



linkage (before) 



"data- 



indirect word with fault tag 



execution 




new indirect word 



Figure 1-5. Resolving a Linkage Fault (Snapping a Link) 
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Access Control Lists 



One way of controlling the sharing and security of information is by using 
access control lists. ACLs, as you have already learned in the New Users ' 
Introduction to Multics , define the access rights for each segment and directory. 
You can grant permission to use your segments and directories by individual 
user, by project, by instance (interactive/absentee), or by combinations of these. 
You can also grant different access to different users of the same segment. A 
good example of using ACLs is a compiler which resides in a segment that can be 
executed but not written. 



For more details on access control, see the MPM Reference Guide. 



Administrative Control 



Another kind of information control is administrative. Multics administration 
defines three levels of responsibility: system, project, and user. A system 
administrator allocates system resources among the projects on his system; a 
project administrator allocates project resources among the users on his project; 
a user can manage his own data through storage management and access controls. 



Your project administrator can define the environment of the users under 
his project. He can give you complete control in creating your own process, or 
he can limit the requests and commands available to you. He can determine the 
dollar limit that you may incur in a single month (or other period of time), and 
arrange things so you'll be automatically logged out if you exceed this limit. 
You won't be able to log in again until the next month begins or the limit is 
changed. He can also determine several other items, including whether a user 
can preempt others, specify his own directory, or have primary or standby status 
when logging in. 



You yourself also have flexibility in shaping your programming environment 
on Multics. A good example of this is the special command processor which 
allows you to make abbreviations for your frequently used commands (abbrev). 



For more information on Multics administrative features, refer to one of 
the manuals in the Multics Administrators 1 Manual (MAM) set: 



Project Administrator Order No. AK51 

Registration and Accounting Administrator Order No. AS68 

System Administrator Order No. AK50 
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SECTION 2 



PROGRAMMING ON MULTICS 



Programming on Multics is very different from programming on other systems. 
Many of the constraints and restrictions you may be used to are simply removed. 
The system provides high-level terminal control, data base management, I/O 
interfaces, and data security. There is no need for overlays, chaining or partitions. 



This section explains how to write, compile and execute programs in the 
Multics environment. It also offers advice on revising and documenting programs, 
manipulating segments, and creating storage system links. 



DESIGNING AND WRITING PROGRAMS 



Let's say you've been given specifications for a program which will compute 
the sum of three numbers. Obviously, this is not a realistic task for a computer, 
but it will provide us with a very simple example. 



Of course, the first thing you need to do is to develop a design for your 
program, be it a flow chart, a functional diagram, a hierarchy, or whatever. 
Once you have a good design, the next step is to decide which language you will 
write your program in. The following programming languages are available on 
Multics : 

• APL: A terse, powerful language, with strong data manipulation 

capabilities. 

• BASIC: A simple language for beginners, which can perform string and 

arithmetic operations without much difficulty. 

« 

• COBOL: A business oriented, high-level, English-like language with many 

string and arithmetic capabilities. 

• FORTRAN: A high-level, scientific language designed mostly for arithmetic 

applications, with very limited character manipulation capabilities. 

• PL/I: A very powerful, high-level language that offers almost total 

control over the operations of the program, and has many capabilities 
to manipulate characters and perform arithmetic operations. 

(ALM, the assembly" language on Multics, is also available, but is not recommended 
for general use.) For this program, let's say you choose PL/I. The code for 
your program might look like this: 
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simple_sum: proc options (main); 



/* this program computes the sum of three numbers 



set in the program, 



then prints the answer at 



the terminal */ 



declare 



first_no fixed binary 
second_no fixed binary 
third_no fixed binary 
the_sum fixed binary 



sysprint file, 



(17), 
(17), 
(17), 
(17); 



/* 
/* 
/* 
/* 
/* 



the 
the 
the 
the 
the 



first number */ 
second number */ 
third number */ 
answer */ 



terminal output */ 



/* set the three numbers */ 

first_no = 123; 
second_no = 456; 
third_no = 789; 

/* add them up */ 

the_sum = first_no + seeond_no + third_no; 

/* print the answer */ 

put skip list ("The sum of the three numbers is:", the_sum); 
put skip; 

end simple__8Uiu; 



Notice the use of sysprint for the terminal output. For more information on 
this, see "Using the Terminal for I/O" in Section 4. 



Source Segments 



The next step is to create a segment containing your code. You can input 
your code by using any one of several text editors. Two editors you are already 
familiar with are Qedx. and Emacs. Detailed information on these editors is 
available in the Qedx Users 1 Guide (Order No. CG40) and the Emacs Users 1 Guide 
(Order No. CH27) respectively. Of special interest to programmers are the 
programming language modes available in Emacs. The FORTRAN, PL/I and ALM modes 
provide editing environments which facilitate the creation, formatting and debugging 
of programs written in these languages. 



Two more editors will be introduced here. One is Edm. This is the most 
basic Multics editor and is described in Appendix D of this manual. The other 
is Ted. Ted is a more advanced version of Qedx, which offers many advantages. 
These include more flexibility in addressing characters within a line, two types 
of input mode, regular and bulk, and more ways of manipulating buffers. Ted is 
a programmable editor, which means that you can write character manipulation 
programs in the Ted editor language. Other Ted features include sorting and 
tabbing capabilities, the ability to translate letters from upper to lower case 
and vice versa, and the ability to have lines fill and adjust. For more information 
on Ted, use the help command. 



The segment that your source code is stored in is called a source segment . 
Once your source segment is created, you should give it an entryname which 
follows the Multics convention for such names. This convention is to add a dot 
suffix to the end of the name indicating which language the program is written 
in* Thus, the form for a source segment entryname is: 
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program_name . lang_name 
A good name for your program would therefore be: 

simple_sum.pl1 

Some other examples of program names are: 

ran_num_gen . basic 
payroll. eobol 
square_root . f ortran 

(Remember that upper and lower case characters are not interchangeable on Multics. 
Thus, "payroll. cobol" and "Payroll . cobol" are two different names. See the MPM 
Reference Guide for more information on naming conventions.) 



You will probably find it useful to create several different directories 
for yourself, each containing a different sort of segment. For example, you 
could have one directory for the final (debugged) versions of your programs, one 
directory for the programs you are writing or revising, another directory for 
test data, etc. If you write programs in several different languages, you could 
also have directories for programs in each language. (Remember that your segments 
are not physically located in directories any more than you are physically in 
the phone book. When a segment is said to be "in" a directory, it means that 
the directory contains an entry for the segment.) 



COMPILING PROGRAMS 



Multics provides a compiler for each higher level language it supports. 
Compilers are system programs which translate source code into object code, 
machine level language that is executable by the hardware. The input to a 
compiler is a source segment. The output of a compiler is a corresponding 
object segment . (This discussion does not apply to APL, which is an interpreted 
language. There is no APL compiler and no APL object segment.) Your working 
directory is always assumed to be the location of the source segment you want to 
compile, and the intended location of the object segment you want to create, 
unless you say otherwise. 



To execute a compiler, you invoke it as a command, with a command line 
which looks like this: 

language_name path {-control_arguments } 

where language_name is the name of the language your program is written in, path 
is the entry name of your source segment, and { -control_arguments } are any of a 
number of optional control arguments you can supply to the compiler. Several of 
these control arguments instruct the compiler to create a listing segment in 
your directory. (No compile listing is produced by default.) This segment has 
the same entryname as your source segment, but with a suffix of "list" instead 
of "pl1" or whatever. A listing segment contains a line-numbered list of your 
source program, plus information that is useful for understanding, debugging, 
and improving the performance of your program. 



The control arguments which produce a listing segment are: 
-list 

produces a complete source program listing including an assembly-like listing 
of the compiled program. Use of this control argument significantly increases 
compilation time and should be avoided whenever possible by using -map. 
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-map 

produces a partial source program listing of the compiled program which 
should contain sufficient information for most online debugging needs. 



Another useful control argument is: 
-table 

generates a full symbol table for use by symbolic debuggers. The symbol 
table is part of the symbol section of the object program (discussed later 
in this section) and consists of two parts: a statement table that gives 
the correspondence between source line numbers and object locations, and a 
name table that contains information about names actually referenced by the 
source program. This control argument usually causes the object segment to 
become significantly longer, so when the program is thoroughly debugged, it 
should be recompiled without -table. 

See the MPM Commands under the specific compiler for detailed information on all 
of the control arguments and the information they provide. Also see the various 
Language Users 1 Guides. 

So, your command line for compiling your program might look like this: 
! pl1 simple_sum . pi 1 -map 



In this and all interactive examples in this manual, an exclamation point 
is used to indicate a line that you type at the terminal. You do not type the 
exclamation point, nor does Multics type it as a way of prompting you. It is 
strictly a typographical convention, to distinguish between typing done by you 
and typing done by Multics. 



In reality, you don't have to type the dot suffix component of your entryname. 
The compiler assumes that the input is a source segment, and will search your 
working directory (or whatever directory you T re using) for the segment with the 
appropriate suffix. Thus: 

! pl1 simple_sum.pl1 

means exactly the same to the compiler as: 

! pl1 simple__sura 



If your source code is clean and the compile is successful, an object 
segment is placed in the directory you're using, with the same entryname as your 
source segment, but stripped of the language name suffix: 



So, if you execute this command line: 

! pl1 simple__sum -map 

then you list your working directory, you'll see: 

simple_sum 
simple_sum.pl 1 
simple_sum. list 



Your listing segment, simple_jsum. list , can be printed on your terminal 
with the print command, or printed on paper with the dprint command. Since 
listing segments take up a large amount of space, the sensible thing to do 
is to dprint the segment, then delete it: 



ran_num_gen . basic 
payroll. cobol 
square_root . f ortran 



> 
> 
> 



ran_num_gen 

payroll 

square_root 



! dprint -delete simple_sum . list 
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If there are problems with your source code, the compiler will produce 
error messages. The compiler can detect errors according to the definitions of 
the language involved. These include typing errors, syntax errors, and semantic 
errors. These messages are printed for you at your terminal. The format and 
details of error messages vary from compiler to compiler. The following is a 
sample PL/I error message: 

ERROR 158, SEVERITY 2 ONLINE 30 

A constant immediately follows the identifier "zilch" 
SOURCE: a = zilch 4; 



If your compile is taking a long time, you can issue a QUIT signal and take 
a look at your ready message. Since a ready message contains the amount of CPU 
time used since the last ready message, if the CPU times on your last two 
messages are different, you know your compilation is working. To resume it, 
type start. You can also use the progress (pg) command to get information on 
how a command's execution is going. To check on your compile of simple_sum . pi 1 
with the -map control argument, you would type: 

! progress pl1 simple_sum -map 

The system would periodically type information about the pl1 command T s progress 
in terms of CPU time, real time, and page faults . (A page fault occurs when a 
page of a referenced segment is not in memory. ) See the MPM Commands for a 
detailed explanation. 



Object Segments 



As you may remember from the discussion of dynamic linking in Section 1, an 
object segment is an executable module. This is quite different from other 
systems, where the object module which is the output of the compiler cannot be 
executed until it has been through some kind of linkage editing to become a load 
module. On Multics, there is no such distinction between an object module and a 
load module. Thus, there is no need for you to determine in advance the absolute 
addresses of programs in memory, or give instructions for linking and calling 
programs or loading them. All compiled programs are ready to run. 



Most higher level languages supported by Multics compile into Multics standard 
object segments. These are divided into several sections. The first section is 
called the text section and contains the binary machine instructions that were 
translated from the source code and are executed by the processor. The next 
section is the definition section , which defines the names and locations of 
entry points present in the segment, and the names of external entry points used 
by the segment. An entry point is a symbolic offset within a segment. (See "A 
Naming Convention" in Section 3») After the definition section comes the linkage 
section , which serves as a template of all virtual addresses for all external 
entry points used by the program. It contains per-process information used by 
the dynamic linker to resolve these external references. The next section is 
tne static section , which contains data items to be allocated on a per-process 
basis. (This section may be included in the linkage section, and not exist as a 
separate section.) Then there is the symbol section , which contains information 
on all the variables declared in the program. The symbol section is always 
present in the object segment. If -table is specified when the program is 
compiled, then a symbol table is included in this section. Some compilers (e.g., 
pl1) support the -brief_table control argument, which produces a shorter symbol 
section. Finally there is the object map , which contains the lengths and offsets 
for each section of the object segment. Details about the format of object 
segments and what each section contains may be found in the MPM Subsystem Writers 1 
Guide. 
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Where the standards for the source language permit, all object segments 
produced by Multics are: 

• pure: the object segment contains no code that modifies itself during 

execution. Information about calls outside the segment is copied into 

a special segment, and all modifications are made to the copy. The 

same segment can be executed by more than one user. No copies of 

object segments are made on a per-user basis; there is one shared 
segment in the address space of all who use it. For example, even 

when multiple users are simultaneously compiling COBOL programs, only 
one copy of the COBOL compiler is in use. 

• recursive: the object segment can call itself. 

• in standard format: the calling protocols for object segments are the 
same irrespective of the higher-level language of origin. This means 
that a program in one language can call a program in another language. 
Programs can also access any data or file which can be described by 
data types supported by the particular language. 



EXECUTING PROGRAMS 



Now that you have an object segment, you are ready to try executing your 
program. To do this, all you have to do is type the name of your program from 
command level. The entryname is understood as a command — the system is instructed 
to find your program and execute it, just as when you type the name of a command 
(like list), the system is instructed to find the program by that name and 
execute it. Source and object segments are both permanent (they don't have to 
be copied to a special directory to be saved), so your program can be run over 
and over until you choose to delete it. 



Some Results of Execution 



• The program runs to normal termination and you get a ready message, 
indicating that execution was successful. 

r 10:29 3.0 350 

• The program pauses for input from your terminal. 

• The program halts because of a breakpoint you've put in it for debugging 
purposes . 

• The program runs to normal termination, but the output you get is 
wrong. 

• The program halts because you issue a QUIT signal, and the system 
responds with a ready message indicating a new command level: 

! QUIT 

r 10:40 0. 1 497 level 2 

• The program halts because of an execution error. Examples of such 
errors are overflows, underflows, data conversions, and undefined 
references. The system prints an error message, then gives you a 
ready message indicating a new command level: 

Error: Exponent overflow by >udd>Pro j A>MacSissle>bad_pgm \ 1 43 
(line 33) 

System handler for condition returns to command level 
r 10:38 0. 185 98 level 2 
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The new command level means that you are again in a position to invoke 
commands. There are some special commands that can be put to appropriate use 
here, such as the release, start, program_int errupt , or probe commands. The 
release command returns you to the original command level--the work you were 
doing at the time of the interrupt is simply discarded. The start command 
resumes execution where it left off . The program_interrupt command returns execution 
to a predetermined point from which to resume execution. For the use of the 
probe command see Section 5, "Debugging Tools." 



Multics will provide you with as specific an error message as possible. 
One common error that happens to almost everyone at some time or other is the 
f ol lowing: 

Error: record_quota_overf low condition by <program__name> 

This message means that you have run out of storage space in the system. The 
best way to fix this situation is to delete unneeded segments and type start. 
(For descriptions of other common error messages, see Mult ics Error Messages : 
Primer and Reference Manual , Order No. CH26.) 



REVISING AND DOCUMENTING PROGRAMS 



If you edit your program and recompile it, you may want to save the old 
object segment instead of replacing it with the new one. In the process of 
developing and testing new versions of a program, you may in fact end up with 
several versions, all of which you want to keep. Here are some wavs you can do 
it: 

# You can move the old object to another directory, using the move command: 

! move simple_sum obsolete__pl 1__ob j>simple__sum 

# You can copy the faulty source (should you wish to save it as well) 
and give a new name to the edited version using the copy and rename 
commands : 

! copy simple_sum.pl1 obsolete__pl 1__source>simple_sum.pl 1 
! rename simple_sum . pi 1 new_jsimple_sum . pi 1 

# You can change the name of the old object: 

! rename simple_jsum old_simple_sum 

You need to be aware of certain dangers involved in renaming segments which are 
already known to your process. Renaming a segment doesn't change the association 
between the segment name and the segment number. So, if pgma calls pgmb, then 
you rename pgmb as badb, create a new pgmb, and run pgma again, when pgma calls 
pgmb, it will end up with the old badb instead of the new pgmb. For more 
information on the association between segment names and segment numbers, see "A 
Note on Initiated Segments" in Section 3- 



If you ever get confused as to which version of your source program is 
which, you can use the compare_ascii (cpa) command, which compares ASCII segments 
and prints any differences. 



Remember that final versions of your programs should be correctly formatted 
to improve their readability. There are several Multics commands which can help 
you do this. For example, the indent (ind) command indents free-form PL/I source 
code according to a set of standard conventions. For another example, the 
format_cobol_source (fcs) command converts free-form COBOL source programs to a 
fixed format. These commands also detect and report certain types of syntax 
errors, and can be used for pre-compile examinations. 
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Your final versions should also be well-documented. There are two kinds of 
documentation for programs. One is internal, and consists of a step-by-step 
description of what the program does. This sort of documentation is best created 
by the generous use of comments throughout your code. The other kind of documentation 
is external, and consists of a more general description of the programs purpose, 
design, and use. Writing info segments is an excellent way of creating this 
sort of documentation. (Remember that the information in an info segment is 
printed using the help command). 



Finally, all of your source and object segments should have the proper 
access set, so only the appropriate people can use them. 



SAMPLE TERMINAL SESSIONS 



Figure 2-1 displays the interaction between Multics and the user Karen 
KacSissle as she logs in and writes, compiles, and executes the simple_sum program. 
MacSissle uses the Qedx editor to put the program online, the pl1 command to 
compile it, and the program name (without the language suffix) to execute it. 
Note that MacSissle does not have the usual ready message. She sets her message 
to "Karen is here" by using the general__ready (gr) command in her start_up.ec, 
the special exec_com that runs each time she logs in. (See the MPM Commands for 
information on the use of general_ready . ) 



In Figure 2-2, user Tom Smith is shown writing a program called times_2, 
which accepts an integer and prints the value of 2 times that integer. Smith 
takes advantage of the terminal for both input to and output from his program. 



A Note on Examples 



Because Multics is written mainly in PL/I, you may find that its runtime 
environment is somewhat oriented towards the convenience of PL/I programmers. 
Ways to take advantage of this orientation are presented in Appendix A, "Using 
Multics to Best Advantage". However, as mentioned in the preface, this manual 
is intended to be useful for all programmers. Although the majority of the 
examples are given in PL/I, there is no need to be discouraged if you aren't 
familiar with this language. Most of the examples are extremely simple. To see 
how you could write the same program in either PL/I, FORTRAN , or COBOL, see 
Section 4, "Using the Terminal for I/O". 



ARCHIVING SEGMENTS 



Segments in Multics are assigned space in increments of pages (4096 characters) . 
This can be very wasteful if you have many short files stored in the system. 
The archive (ac) command allows you to combine several segments into a single 
segment called an archive . Once in an archive, the individual segments are 
called components of the archive segment. Packing segments together in this way 
can produce significant savings in storage allocation and cost. 



By invoking the archive command with different arguments, you can manipulate 
the archive segment in a variety of ways. For example, in addition to creating 
your archive, you can also get a table of contents that names each component in 
the archive, extract one or more components from the archive, update and replace 
one or more components, and delete individual components. 
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login KacSissle 
Password : 

MacSissle ProjA logged in 03/18/81 0921.4 mst Wed from VIP7801 
terminal "none" . 

Last login 03/18/81 0726.2 mst Wed from VIP7801 terminal "none". 
Karen is here 

qedx 
a 

simple_sum: proc options (main); 

/* this program computes the sum of three numbers set in the program, 
then prints the answer at the terminal */ 

declare 

sysprint file, /* the terminal output */ 

first_no fixed binary (17), /* the first number */ 

second_no fixed binary (17), /* the second number */ 

tbird_no fixed binary (17), /* the third number */ 

the__sum fixed binary (17); /* the answer */ 

/* set the three numbers */ 

first_no = 123; 
second_nc = 456; 
third_no = 789; 

/* add them up */ 

the__sum = first_no + second_no + third_no; 

/* print the answer */ 

put skip list ("The sum of the three numbers is:", the_sum); 
put skip; 

end simple sum; 

\f 

w simple_sum.pl 1 
Q 

Karen is here 

pl1 simple_sum 
PL/I 

Karen is here 
simple__sum 

The sum of the three numbers is: 1368 
Karen is here 



Figure 2-1. Sample Terminal Session ir\ 
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! login TSmith 
Password : 

i 

TSmith ProjA logged in 06/07/79 0937-5 mst Tue from ASCII 
terminal "234". 

Last login 06/06/79 1359-8 mst Mon from ASCII terminal "234". 

A new PL/I compiler was installed; type: help pl1_new 
Rates for CPU usage have changed; type: help prices 
r 9:37 1.314 30 

! qedx 

! a 

! times_2: proc; 

! declare ( num , product ) fixed bin(17); 

! declare (sysin input, sysprint output) file; 

! put list ("Enter integer"); 

! put skip; 

! get list (num); 

! product = num*2; 

! put skip list ("2 times your integer is:", product); 

! put skip; 

! close file (sysin), file (sysprint); 

! end ; 

! \f 

! w times_2.pl 1 

! q 

r 9:40 4.875 62 

! pl1 times_2 
PL/I 

r 9:41 2.906 272 

! times_2 

Enter integer 
! 19 

2 times your integer is: 38 
r 9:43 0.231 50 



Figure 2-2. Sample Terminal Session #2 
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For more information about the archive command and its use, refer to the MPM 
Commands . 



BINDING SEGMENTS 



The Multics bind (bd) command is used to merge several separately compiled 
object segments into a single executable object segment called a bound segment . 
Tne binder is primarily an optimizer, which saves search time and link snapping. 
It resolves as many external references as it can in order to avoid the necessity 
of resolving them at run time. These references are resolved without recourse 
to the search rules--the binder looks only in the programs that are being bound, 
and rejects any programs in which there are ambiguous external references. 



Binding offers the advantages of taking up less storage for the object 
code, decreasing execution time, and avoiding many linkage faults that would 
otherwise occur if the bound programs referenced each other from separate segments. 
Those programs that you call frequently and that are interrelated (ie, reference 
one another) should be bound to improve program efficiency. The segments must 
be archived before they are bound. 



For more information about the bind command, refer to the 'MPM Commands. 
Also, the MPM Subsystem Writers 1 Guide provides information on the structure of 
bound segments. 



LINKS 



The word "link" is used for two separate things in Multics: an intersegment 
link and a storage system link . This can be confusing for beginners, but once 
you know the system, things are usually clear from their context. 

An intersegment link is an interprocedure reference, resolved by the linker. 
This kind of link is described in Section 3, "Dynamic Linking". 



A storage system link is essentially a "pointer" to a "target". This kind 
of link is described here. A storage system link is catalogued in a directory 
like a segment, but just gives the pathname of some other place in the directory 
hierarchy. The target of such a link is usually a segment, but it can also be a 
directory, or even another link. A storage system link enables you to access a 
segment located in some other portion of the directory hierarchy without actually 
making a copy of it, just as if it were catalogued in your own working directory. 
This is one of the ways in which Multics facilitates sharing. 



Multics allows you to create a link anywhere in the storage system as long 
as you have the proper access to the directory in which the link is to be 
placed. You invoke the link (lk) command to create a link and the unlink (ul) 
command to delete a link. (Refer to the MPM Commands.) To see a list of the 
links you have in your working directory, you can use the list command with the 
-link control argument. 
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SECTION 3 
DYNAMIC LINKING 



As the discussion of dynamic linking in Section 1 indicated, external references 
on Multics are resolved when a program is executed. When the system comes 
across an unresolved reference, it uses what are known as search rules to find 
the necessary segment and establish the link. The purpose of this section is to 
explain how the search rules operate, then to show you some of the uses of 
dynamic linking. 



A NAMING CONVENTION 



Due to a Pl/I extension which is local to Multics, the "$" character is 
understood when it appears as part of an external name. a$b is interpreted to 
mean segment a, entry point b. (Remember that an entry point is a symbolic 
offset within the segment. Refer to the discussion of two-dimensional addressing 
in Section 1.) Thus, hcs_$initiate , which will be discussed later in this section, 
is interpreted to mean segment hcs_, entry point initiate. 



SEARCH RULES 



Let ! s suppose that you are writing a new version of the Qedx Text Editor, 
and have a segment in your working directory named "qedx". If you type "qedx" 
on your terminal, you are instructing Multics to find the program named qedx and 
execute it. But which qedx do you want--yours or the system's? To make the 
situation a little bit more complicated, let's suppose that one of your coworkers 
is also writing a new version of Qedx, and has a segment in one of his directories 
named "qedx", to which you have access. You might want to run his program 
sometimes instead of yours or the system's. 



In each case, it's up to Multics to figure out which segment you want. The 
way Multics does this is by searching. To understand why Multics searches the 
way it does, you first need to know some of the assumptions it works under. 



Once you have Invoked some program or accessed some data base, Multics 
assumes there is a good chance you will do so again. If the item is in your 
address space, that cuts down on the system overhead required to make a complete 
search for it a second or third time. So Multics keeps track of all the work 
you do after you login. It records your movement through the file system, 
noting each item it has located for you and putting these items in your address 
space. Multics also assumes that any time you use a reference name which you 
have already used, you mean the same item you meant the first time. (A reference 
name is a name used to identify a segment that has been made known by the user. ) 
The name of the item and the information the system needs to find it are recorded 
in a table called the reference name table. Segments in this table are referred 
to as initiated segments. 
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The search rules are a list of directories which are searched in order 
until the desired segment is found. The standard search rules are: 

1 . init iated_segments 

Reference names for segments that have already been made known to a specific 
process are maintained by the system. A reference name is associated with 
a. segment in one of four ways: 

a. use in a dynamically linked external program reference. 

b. use in an invocation of the initiate command. 

c. a call to hcs_$initiate , hcs_$init iate_count , or hcs_$make_seg with a 
nonnull character string supplied as the ref_name argument. These 
hcs__ entry points are described in the MPM Subroutines. 



d. a call to hcs_$make_ptr or hcs_$make_entry (described in the MPM 
Subroutines). 



2. ref erencing_dir 

The referencing directory contains the segment whose call or reference initiated 
the search. So, if pgma calls pgmb, and pgmb isn't in the reference name 
table, the system looks for pgmb in the directory where pgma resides. 



3. working_dir 

The working directory is the one associated with you at the time of the 
search. This may be any directory established as the working directory by 
either the change_wdir command or the change_wdir__ subroutine (described in 
the MPM Commands and MPM Subroutines respectively). The initial working 
directory is your home directory. 

4. system libraries 

The system libraries are searched in the following order: 

>system_library_standard 

This library contains standard system service modules, i.e., most system 
commands and subroutines. 

>system_library_un bund led 

This library contains Multics Separately Priced Software. 

>system_library_1 

This library contains a small set of subroutines that are reloaded 
each time the system is reinitialized. 

>system__library_tools 

This library contains software primarily of interest to system 
programmers . 

>system_library_auth_roaintained 

This library contains user maintained and installation maintained 
programs . 

You can see what your process's current search rules are by using the 
print_search__rules (psr) command: 
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! psr 

initiated_segments 

referencing_dir 

working_dir 

>system__library__standard 

>system__library_unbundled 

>system_library_1 

>system_library_tools 

>system_library__auth_maint 



Note that, according to these search rules, if you have in your working 
directory a program with the same name as a system command or subroutine, your 
program will be used rather than the system's. Don't give your programs the 
same names as those of system programs, unless you really are trying to replace 
them. Here is an example of the trouble you can get into when you duplicate the 
name of a system program. Suppose you have a program of your own which creates 
an output file and you name the file "list." If you run your program, then try 
to list your working directory using the list command, you will get a message 
like this: 

command__processor_: Linkage section not found. list 
The system thinks you are trying to run your output file, list, as a program! 



You can modify your search rules by using the add_search_rules (asr), 
delete__search_rules (dsr), and set_search_rules (ssr) commands, described in the 
MPM Commands. In addition, your system administrator can modify the default 
search rules described above for all users at your site. 



Thus, the first time you invoke a program after login, the system begins 
its search for the segment by looking in the reference name table. The search 
fails there, so it continues through the list of directories in the search rules 
until the segment is found or all the directories have been searched. Subsequent 
invocations of the sane program are much faster, because the system finds the 
program right away in the reference name table. 



A Note on Initiated Segments 



If your program named x references a program named y by means of a call or 
function reference, a dynamic link is established between x and y so that all 
subsequent references to y by x are accomplished by using the segment number 
(the alias for the segment name discussed in Section 1). If you change to a new 
working directory, and execute a program named z that calls a program in this 
new directory named y, the system will establish a dynamic link to the original 
segment y because the reference name y is still associated with the original 
segment and segment number. The system maintains this association until the 
reference is terminated. See Figure 3-1 for an illustration of initiated segments 
working in this way e 
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working_dir_1 




working_dir_2 





x call y 



z calls y 



Figure 3-1. Initiated Segments 
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Segments can be made known to your process by using the initiate (in) 
command. You can list your initiated segments with the list_ref_names (Irn) 
command. References can be terminated by using one of the terminate commands, 
either terminate (tm), t erminat e_refname (tmr), t erminate_segno (tms) or 
terminate_single_ref name (tmsr), which allow you to remove segments from the 
list of segments known to your process. (The new_proc command also erases all 
previous association between segment names and segment numbers, by sweeping out 
your entire address space.) For more detailed information on these commands, 
see the MPM Commands. 



Deleting a segment also terminates it. Recompiling a program unsnaps all 
links in the current process which point to the program, since the location of 
symbolic entry points may be changed by recompilat ion . Both of these actions 
affect only the process performing the operation. Recompiling or deleting a 
segment in one process may cause other processes using the segment to malfunction. 



USES OF DYNAMIC LINKING 



There are many ways in which dynamic linking can be used, but the following 
three are probably the most significant: 

• to permit initial debugging of collections of programs before the entire 
collection is completely coded. 

• to permit a program to include a conditional call to an elaborate 
error handling or other special-case handling program, without invoking 
a search for or mapping of that program unless the condition arises in 
which it is actually needed. 

• to permit a group of programmers to work on a collection of related 
programs* such that each one obtains the latest copy of each subroutine 
as soon as it becomes available. 



The use of dynamic linking in program development is shown by the following 
script. When the script starts, the program "k" and subprogram "y" have already 
been written and compiled by our user KacSissle. 



k: procedure; 




declare (x, y, z) 


entry ; 


declare i 


fixed binary; 


declare (sysprint, sysin) 


file; 


put list ("Which option?"); 




get list (i); 




if i = 1 then call x; 




else if i = 2 then call y; 




else if i = 3 then call z; 




else put list ("Bad option " 


); 


return: 




end k ; 




y: procedure; 




declare sysprint 


file; 


put list ( "y has been called 


it ^ . 


put skip; 




end y; 





In this example and all others like it in this manual, comments on the 
script are distributed throughout the script itself. 
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! k 

Which option? ! 2 

y has been called. 

r 17:11 0. 123 11 



The program "k" is invoked by typing its name. MacSissle calls for option 
2, and the program "y" is called. "k" runs successfully even though two of the 
three subroutines it could call do not exist, because the subroutine it does 
call is available. Since linking is done on demand, and no demand for "x" or 
"z" occurs, their nonexistence does not keep the program from running. 

In the next use of "k", MacSissle asks for an option corresponding to the 
program "z," which doesn : t exist. 



! k 

Which option? ! 3 

Error: Linkage error by >udd>Proj A >MacSissle>k j 152 (line 11) 

referencing z'z 

Segment not found, 
r 17: 11 0.283 90 level 2 



The attempt to call the nonexistent subroutine "z" fails. The linkage 
error handler invokes a second command level, as indicated by the field "Level 
2" in the ready message. The error message shows the full pathname of the 
program attempting to locate "z," and gives the name of the program that could 
not be found. The notation "ziz" means entry point "z" in segment "z." It is 
necessary to separate entry point name from segment name, since a PL/I program 
in a segment could have several entry points with different names. 



Execution of "k" is suspended, since it cannot continue with the call. 
MacSissle has the choice of giving up, or creating "z." She invokes the qedx 
editor and creates the segment. 



! qedx 
! a 

! z: procedure; 

! declare sysprint file; 

! put list ("This is Z") 

! put skip; 

! end z; 

! \f 

! w z . pi 1 
! q 

r 17: 12 0.382 48 level 2 



Now the segment must be compiled to create a callable object segment. 



! pl1 z -table 
PL/I 

r 17: 12 0.234 65 level 2 



With the object segment "z" created, the call from "k" can be restarted. 
MacSissle does this with the start command. 
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! start 

This is Z 
r 17: 12 0, 166 27 



The program finishes successfully. It can now be run with option 3 without 
any additional intervention. 



! k 




Which 


option? ! 3 




This is Z 


r 17: 


13 0.075 18 



For more information on the details of dynamic linking, see the MPM Reference 
Guide sections on object segments, system libraries and search rules. You might 
also want to learn about the resolve_linkage__error (rle) command, which can be 
used to satisfy the linkage fault after your process encounters a linkage error. 
This command is described in the MPM Commands. 



SEARCH PATHS 



Searching is something that Multics has to do all the time. So far we've 
only talked about searching for object segments—what Multics has to do when you 
type the name of a program you want to execute, or your program references an 
external procedure. Multics has to search for other things, too, notably input 
of some kind. For example, the help command requires as input an info segment. 
You can tell the system to look in specific places for the input by creating 
search paths . Search paths have the same basic function as search rules, but 
are used for things like subsystems and language compilers. A set of commands 
similar to those available for modifying search rules are available for modifying 
search paths. These commands are add_seareh_paths (asp), delete_jsearch_j>aths 
(dsp), print__search_paths (psp), set_search_paths (ssp), and where_search_paths 
(wsp). All are documented in the MPM Commands. 



3-7 



AG90-03 



SECTION 4 



INPUT/OUTPUT PROCESSING 



Input/output (I/O) processing on Multics can be handled in many different 
ways. The intent of this section is to show you how to do simple kinds of I/O 
on Multics, and to introduce you to the basics of doing more complex I/O. 



The Multics I/O system handles logical rather than hardware I/O. This 
means that I/O on Multics is essentially device independent. In other words, 
you don ! t have to write your program with a specific device in mind. Most I/O 
operations refer only to logical properties (e.g., the next record, the number 
of characters in a line) rather than to particular device characteristics or 
file formats. To understand how I/O processing on Multics works, you must first 
be familiar with two important terms. 



(1) I/O switch: a software construct through which the file name in your program 
is associated with an actual device. The I/O switch is like a channel, in 
that it controls the flow of data between your program and a device. It 
keeps track of the association between itself and the device and the I/O 
module . 



(2) I/O module: a system or user-written program that controls a physical device 
and acts as an intermediary between it and your program. The I/O module 
knows what the attributes of the device are, and "hides" them from you so 
you don't have to worry about them. It processes the I/O requests that are 
directed to the switch attached to it. The Multics system offers the following 
I/O modules: 



discard^ 

provides a "sink" for unwanted output. 
rdisk_ 

supports I/O directly from/to removable disk packs. (These are packs 
which are allocated in their entirety to a process; they do not contain 
files in the Multics storage system.) 

recordist ream_ 

provides a means of doing record I/O on a stream file or vice-versa. 
syn_ 

establishes one switch as a synonym of another, 
tape_ansi_ 

supports I/O from/to magnetic tapes according to standards proposed by 
the American National Standards Institute (ANSI). 
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tape_ibm_ 
supports 



I/O 



from/to magnetic tapes according to IBM standards. 



t ape_mult_ 
supports 



I/O 



from/to magnetic tapes in Multics standard tape format. 



tape_nstd_ 
supports 



I/O 



from/to magnetic tapes in nonstandard or unknown format. 



tty 



supports 



I/O 



from/to terminals. 



vfile 



supports 



I/O 



from/to files in the storage system. 



Figure h-1 illustrates the flow of data between a program , an I/O switch, an I/O 
module, and a device. 



THE FIVE BASIC STEPS OF INPUT/OUTPUT 



For every input/output data stream you are using, you must follow the 5 
basic steps of Multics I/O processing, which involve attaching an I/O switch to 
an I/O module, opening the switch, performing the data transfer, closing the 
switch, and detaching it from the I/O module. These steps may be accomplished 
outside of your program by means of commands input before and after your program 
runs, or inside your program by means of subroutine calls or language I/O statements. 
(Defaults are arranged so you can often appear to skip these steps, and they 
will be done correctly anyway.) 



( 1 ) Attach the Switch 

This step associates your data with a file in your program. The switch is 
the program's name for each data stream. (In FORTRAN, switches are called 
fileC5, fileIC, etc.) An attachment statement in Multics is comparable to 
a JCL data definition (DD) statement in IBM systems. A switch remains 
attached until you detach it or you issue a new_proc or logout command. 

A switch may be attached by: 



• invoking the io_call command 

• issuing a call to the iox_ subroutine 

• using a language open statement (if the switch hasn't been previously 



attached ) 



using the default attachments associated with PL/I gets and puts, 
FORTRAN reads and writes, or COBOL reads and writes 
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Figure 4-1. Flow of Data 
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(2) Open the Switch 



This step describes the data you're going to use. It tells the system how 
the data is organized (its file type) and how it is to be accessed (its 
mode). Data sets can be organized in four fundamental ways: stream, 
sequential, blocked, and keyed. Only the first two ways will be discussed 
here . 

A stream file is a collection of data that is like free-form text. The 
data is a continuous flow of information, with individual items separated 
by blanks, commas, or newline characters. A stream file can be created, 
examined, and updated via a text editor, and can be meaningfully printed on 
a terminal or line printer, because it contains only ASCII characters. 
It's size is arbitrary. 

^ sequential file is a collection of data that is broken into discrete 
units called records , which have a fixed form. A sequential file is created 
by a program, and is used for information which is meant to be read and 
processed by another program. The data are in the same coded form as data 
stored internally in the computer and can't be printed meaningfully. 

Host tape files are sequential. Disk files may be either stream or sequential. 
Terminal I/O is stream-oriented. 

Data sets can be operated on in three fundamental ways: input only, output 
only, or both input and output. Some of the opening modes of a switch are 
therefore: 



A switch may be opened by: 

• invoking the io_call command 

• issuing a call to the iox_ subroutine 

• using a language open statement 

• using PL/I gets, puts, reads, and writes, FORTRAN reads and writes, or 

COBOL reads and writes—the switch is opened by default 

(3) Perform I/O Operations 

This step is where the data transfer actually occurs. 
Data transfer may be performed by: 

• invoking the io_call command 

• issuing a call to the iox_ subroutine 

• using language defined I/O statements (gets, puts, reads, writes, etc.) 

(4) Close the Switch 

This step tells the system you are through (at least temporarily) with the 
I/O switch. It prevents further access to the data through that switch, 
enables you to re-open the switch later with a different mode, and with 
output disk files and tapes, sets the length of the file. 



si - stream input 

so - stream output 

sio - stream input/output 



sqi - sequential input 

sqo - sequential output 

sqio - sequential input/output 
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A switch may be closed by: 

• invoking the io__call command 

• issuing a call to the iox_ subroutine 

• using a language close statement 

• default (on your program's return), if and only if the switch 

was opened by default 



(5) Detach the Switch 

This step disconnects your program from your data, 
A switch may be detached by: 



• invoking the io_call command 

• issuing a call to the iox_ subroutine 

• using a language close statement 

• default (on your program's return), if and only if the switch 

was attached by default 



USING THE TERMINAL FOR I/O 



The simplest way to do I/O on Multics is to use the terminal. There are 
four standard switches which are attached when your process is created. 



(1) user_i/o: this switch acts as a common collecting point for all terminal 
I/O. It f s attached to your terminal through the I/O module tty_ and opened 
for stream input and output. 

(2) user_input: this switch controls command and data input at the terminal. 
It's attached to user_i/o through the I/O module syn_, and through that to 
your terminal. It's opened for stream input. 

(3) user_output : this switch controls command and data output at the terminal. 
It's attached to user_i/o through the I/O module syn_, and through that to 
your terminal. It's opened for stream output. 

(4) error_output : this switch controls output of error messages at the terminal. 
It's attached to user__i/o through the I/O module syn_, and through that to 
your terminal. It's opened for stream output. 



Figure 4-2 illustrates these standard attachments. 
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Figure 4-2. Standard Attachments 
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If you don't specify switch names and I/O modules when you run your program, 
the system uses these defaults. So, it's possible to write your program using 
the terminal for input and output and not worry about files. For example, here 
is a revised version of our sample program from Section 2, simple_sum. It has 
been renamed any__sum, and changed to accept input typed by the user at the 
terminal in response to a prompting message. The output is typed back on the 
terminal. Notice the use of sysin and sysprint for the terminal input and 
output . 



any_sum: proc options (main); 

/* this program computes the sum of any three 1 to 6 digit numbers typed 
at the terminal, then prints the answer at the terminal */ 

declare 

sysin file, /* the terminal input */ 

sysprint file, /* the terminal output */ 

first_no fixed binary (20), /* the first number */ 

second_no fixed binary (20), /* the second number */ 

third__no fixed binary (20), /* the third number */ 

the_sum fixed binary (24); /* the answer */ 

/* get the three numbers */ 

put skip list ("please type three 1 to 6 digit numbers:"); 
get list (first_no, second_no, third_no); 

/* add them up */ 

the__sum - first_no + second_no + third_no; 

/* print the answer */ 

put skip list ("the sum of the three numbers is:", the_sum); 
put skip; 

end any sum; 



Here are FORTRAN and COBOL versions of the same program, 



c 


This program computes the sum of any three numbers 


typed at the 


c 


terminal, then prints the answer at the terminal. 






integer first__no, second_no, third no 


! the 3 numbers 




integer the_sum 


! the answer 


c 


Get the three numbers 






print, "please type three numbers:" 






input, first_no, second_no, third_no 




c 


Add them up 






the_sum = first_no + second_no + third__no 




c 


Print the answer 






print, "the sum of the three numbers is:", the__sum 






stop 






end 
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Detailed information about how the command utility and active function error 
subroutines can be used from an active function procedure is provided in the MPM 
Subroutines and the MPM Subsystem Writers 1 Guide respectively. 



The same procedure can be programmed to operate both as an active function 
and as a command procedure. Typically when such procedures are called as a 
command, they print on the user's terminal the value of the string they would 
return as an active function. These command/active function procedures are coded 
as active functions and should call cu_$af_return_arg instead of cu_$af arg_count . 
If cu_$af__return_arg returns the error code error_table_$not_act_fnc , tTiey operate 
as commands. If the code returned is zero, they use the returned pointer and 
length to base the return value. Any other nonzero error code should be fatal. 
Note that cu_$af__return_arg always returns a correct argument count even if the 
active function was invoked as a command, so the user can go on to use cu_$arg_ptr 
with no further checking. 



ADDRESS SPACE MANAGEMENT 



When a user logs in, he or she is assigned a newly created process. Associated 
with the process is a collection of segments that can be referenced directly by 
system hardware. This collection of segments, called the address space, expands 
and contracts during process execution, depending on which segments are used by 
the running programs. 



Address space management consists of constructing and maintaining a 
correspondence between segments and segment numbers, segment numbers being the 
means by which the system hardware references segments. Segment numbers are 
assigned on a per-process basis (i.e., for the life of the process), by supplying 
the pathname of the segment to the supervisor. This assignment is referred to 
as "making a segment known." Segments are made known automatically by the dynamic 
linker when a program makes an external reference; making a segment known can 
also be accomplished by explicit calls to address management subroutines. In 
addition, when a segment is made known, a correspondence can be established 
between the segment and one or more reference names (used by the dynamic linker 
to resolve external references); this is referred to as "initiating a reference 
name." When dynamic linking is the means used to make a segment known, the 
initiation of at least one reference name is performed automatically. (For more 
information on reference names, see "Reference Names" in Section 3 and "Making a 
Segment Known" below.) A general overview of dynamic linking is given below. 



Dynamic Linking 



The primary responsibility of the dynamic linker is to transform a symbolic 
reference to a procedure or data into an actual address in some procedure or 
data segment. In general, this transformation involves the searching of selected 
directories in the Multics storage system and the use of other system resources 
to make the appropriate segment known. The search for a referenced segment is 
undertaken after program execution has begun and is generally required only the 
first time a program references the address. 



The dynamic linker is activated by traps originally set by the translator in 
the linkage section of the object segment. These traps are used by instructions 
making external references. When such an instruction is encountered during 
execution, a fault (trap) occurs and the dynamic linker is invoked. 
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The dynamic linker uses information contained in' the object segment's 
definition and linkage sections to find the symbolic reference name. (For a 
detailed description of these sections, see "Multies Standard Object Segment" in 
Section 1 in the MPM Subsystem Writers' Guide.) Using the search rules 
currently in effect, the dynamic linker determines the pathname of the segment 
being referenced and makes that segment known. The linkage trap is modified so 
that the fault does not occur on subsequent references; this is referred to as 
snapping the link. 
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identification division . 
program- id . any sum. 
author. KMacSissle. 
date-written. February 1981. 
date-compiled . 

remarks. This program computes the sum of any three 1 to 6 digit 
numbers typed at the terminal, then prints the answer at the 
terminal . 



environment division . 
configuration section, 
source-computer. Multics. 
object-computer. Multics. 

data division* 
working-storage section. 

zeroes . 
zeroes . 
zeroes, 
zeroes. 



01 first-no 

01 second-no 

01 third-no 

01 the-sum 



pic 9(6) value 

pic 9(6) value 

pic 9(6) value 

pic 9(7) value 



procedure division. 



100 -get -three-numbers . 

display "please type three 1 to 6 digit numbers". 

display "(numbers less than 6 digits long must be zero-filled,". 

display " and each number must be typed on a new line):". 



accept first-no. 
accept second-no. 
accept third-no. 



200-add-them-up. 

compute the-sum = first-no + second-no + third-no. 

30 0-print-t he-answer . 

display "the sum of the three numbers is: ", the-sum. 
stop run. 



USING SEGMENTS AS STORAGE FILES 

When your application requires the use of a storage file for I/O, the 
easiest thing to do is to use a segment in your working directory (or a segment 
in another directory to which you have created a link). In your program, you 
must do the following: 

(1) Give the file a name and declare it as a file; 

(2) Open it (connect it to your program, prepare it for processing, and position 
it at the beginning); 

(3) Do data transfer via one or more get, put, 'read or write statements (depending 
on the language you 1 re using); 

(4) Close it (disconnect it from your program). 
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Here is a revised version of the any_sum program . It f s been renamed comput e_sum , 
and changed so that it gets its input from a segment in your working directory 
called in_file. The output goes to another segment in your working directory 
called out file. 



compute_sum: proc options (main); 

/* this program computes the sum of three 1 to 6 digit numbers read from 
an input file, then writes the answer to an output file */ 

declare 

in_file stream file, /* the input file */ 

out_file stream file, /* the output file */ 

first_no fixed binary (20), /* the first number */ 

second_no fixed binary (20), /* the second number */ 

third__no fixed binary (20), /* the third number */ 

the_sum fixed binary (24); /* the answer */ 

/* open the files */ 

open file (in__file) input, 

file (out_file) output; 

/* get the three numbers from the input file */ 

get file (in_file) list (first_no, second_no, third_no); 

/* add them up */ 

the_sum = first_no + second_no + third_no; 

/* put the answer in the output file */ 

put file (out file) list (the_sum); 



/* close the files */ 

close file (in_file), 
file (out file); 



end comput e_sum; 



Doing I/O this way also takes advantage of the default switches and. modules. 
The open statement attaches and opens the switch, the close statement closes and 
detaches the switch. 



What if the files you need to use are not segments in your working directory? 
One thing you can do, if you're a PL/I programmer, is to use the title option on 
your open statement. For example: 

open file (in_file) title 

("vfile_ >udd>ProjA>MaeSissle>data_files>test_file_1 ") input; 

where 

vfile_ >udd>ProjA>MacSissle>data_f iles>test_f ile_1 

is an example of an attach description . An attach description is a string of 
characters which identify the name of an I/O module and options to control its 
operation. In this case, the only option given is the source/target of the 
attachment (i.e., the name of the device or file). 



AG90-03 



Other languages have constructs which are somewhat similar to the PL/I 
title option. In FORTRAN, there is the attach specifier, which is used on an 
open statement. In COBOL, there is the catalog-name clause. See the Language 
Users 1 Guides for information on how to use these constructs. 



USING I/O COMMANDS AND SUBROUTINES 



The use of I/O commands and subroutines is where I/O processing may become 
more complex. The following discussion is > not intended to fully explain their 
use, but rather, to introduce the basic concepts involved. For more information, 
refer to the MPM Reference Guide, Section 5. Information is also available in 
the Language Users' Guides. 



The command for performing operations on designated I/O switches is io_call 
(io). Its syntax is: 

io opname switchname {args} 



It is used as follows: 
(1) To attach a switch: 

syntax: io attach switchname modulename {args} 

example: io attach my_switch vfile_ >udd>Pro j A>MacSissle>my_f ile 

(vfile_ >udd>Pro jA>MacSissle>my_f ile is another example of an attach 
description. ) 



(2) To open a switch: 

syntax: io open switchname mode 

example: io open my__switch sequent ial_input 



(3) To close a switch: 

syntax: io close switchname example: io close my__switch 



(4) To detach a switch: 

syntax: io detach switchname example: io detach my_switch 



The io__call command is used outside of your program. A typical sequence at 
command level would involve attaching and opening the switches, running your 
program, then closing and detaching the switches. (Switches that are attached 
and opened at command level should usually be closed and detached at command 
level. However, they can also be closed explicitly by the program using language 
close statements.) 



Other I/O-related commands include: 
close__file (cf) 

closes specified FORTRAN and PL/I files. This command is very useful if 
your program opens a file, then terminates unexpectedly before closing 
it. You must close the file before you run the program again, or you 1 11 
get an end-of-file error. 
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copy_cards (ccd) 

copies specified card image segments from the system pool storage into 
your directory. The segments to be copied must have been created using 
the Multics card image facility. 

copy_file (cpf) 

copies records or lines from an input file to an output file. 

display_pl 1 io_error ( dpe) 

describes the most recent file on which a PL/I I/O error was raised and 
displays diagnostic information associated with that error. 

file_output (fo) 

directs all subsequent output over user_output to a specified segment. 

print_attach_table ( pat ) 

prints information about I/O switch attachments. 

revert_output ( ro) 

restores all subsequent output to the previous device. 

stop_cobol_run ( scr ) 

causes the termination of the current COBOL run unit. 

terminal_output (to) 

directs all subsequent output over user_output to a terminal. 



Three of these commands can show you a little about how switches work. Type 
"pat" on your terminal and the system will print this: 



user_i/o 


tty_ -login__channel 


stream_input_ 


^output 


user__input 


syn_ user_i/o 


user_output 


syn_ user_i/o 


error__output 


syn_ user_i/o 



You can see from this that user__i/o is attached via the module tty_ to the login 
channel, and user_input, user__output , and error_output are attached via the module 
syn__ to user_i/o. 



Type "fo my_file; pat; ro; pr my__file" on your terminal and the system will 
print something like this: 



my__file 03/10/81 1124.0 est Mon 

user_i/o tty_ -login_channel 

stream_input_output 
user_input syn_ user_i/o 

user_output syn_ fo_! BBB JKqdcZHXHFf 

error__output svr L. user_i/o 

fo_save__lBBBJKqdcZJXgxW 
syn_ user_i/o 

fo_! BBB JKqdcZHXHFf vfile_ >udd>Pro j A>MacSissle>my_f ile -extend 
stream_output 



You can see from this that user__output was attached via vfile__ instead of syn_. 
(Refer to Figure 4-3.) For complete information on all of these commands, see 
the MPM Commands. 
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The most important subroutine for doing I/O is iox_. It is called from 
within your program just like any other subroutine, and can be used to attach, 
open, close and detach switches, as well as to read and write records, and 
perform various other I/O operations. Another subroutine for doing I/O is ioa__, 
which is used for producing formatted output; it can be very handy. The use of 
these subroutines is beyond the scope of this manual. Detailed information is 
available in the MPM Subroutines. 



CARD INPUT AND CONVERSION 



You may have programs punched on cards that you would like to compile and 
run under Multics. The standard way of handling a card deck on Multics is to 
place the deck in a card reader and read it into a system pool. Once this is 
done, you log in on a terminal, and transfer the card file from the system pool 
to your working directory using the copy__cards command already mentioned. 



A minimum of three control cards must accompany your deck. These control 
cards identify you to the system, and specify the format of the card input you 
are submitting. There are two kinds of card input on Multics. One is bulk data 
input , which is usually a program or a data file. The format of a card deck for 
bulk data input is shown below: 



++DATA DECKJNAME PERS0N_ID PROJECTED 

++PASSWORD PASSWORD 

++CONTROL OVERWRITE 

++AIM ACCESS CLASS OF DATA CARDS 

++FORMAT PUNCH_FORMAT MODES 

++INPUT 



(user data cards) 



The three cards required as a minimum are the first, which is an identifier 
card, the second, which is a password card, and the last, which signals the end 
of control input. 



The other kind of card input is remote job entry , which is a series of 
Multics commands to be run as an absentee job. For information on absentee 
jobs, and the format of a card deck for remote job entry, see Section 7. For a 
complete explanation of all the Multics control cards, see Appendix C of the MPM 
Reference Guide. 
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gure 4-3. Attachments After Execution of file_output Command 
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SECTION 5 



A DEBUGGING TOOL 



A variety of debugging tools are available on Multics. They allow you to 
look at your program piece by piece, in a way that is closer to the way the 
machine sees it. The most powerful of these tools is an interactive program 
named probe, which permits source-language breakpoint debugging of PL/I, FORTRAN, 
and COBOL programs. To understand the discussion of probe given later in this 
section, you must first know a little about the Multics stack . 



THE STACK 



Each process has associated with it a stack segment (called the stack) that 
contains a history of the environment. The stack is essentially a push down 
list which contains the return points from a series of outstanding interprocedure 
calls. It also holds storage for automatic variables. If you were to stop a 
running process and trace its stack, you would find, starting at the oldest 
entry in the stack, a record of the procedures used to initialize the process, 
followed by the command language processor, followed by the procedure most recently 
called at command level and any procedures it has called. Your stack can be 
visualized as follows: 



The lines in the illustration above define stack frames . As control passes 
from program to program within the system, your stack "grows" new stack frames: 



5-1 



AG90-03 



Figure 5-1 gives a pictorial view of what the stack might look like at 
different times during the execution of a program* In Figure 5-1a, the last 
frame of the stack is for the command level programs. From command level, you 
can type commands at the terminal. Once a command is typed, that program is 
called and a stack frame immediately allocated for it. (This is shown in Figure 
5-1b). The stack remains in this state for the duration of execution of the 
program. 



Header 



initial 
nrosram 



first 
command 
level 



Header 



initial 
program 



first 
command 
level 



program 



Header 

initial 
program 



first 
command 
level 



program 



( signal^ 
overhead) 



second 
command 
level 



QUIT 

information 



Figure 5-1. State of Stack 



(a) State of Stack after Login 

(b) State of Stack after Command is invoked 

(c) State of Stack after QUIT 
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Figure 5-1c depicts the stack after a QUIT is signalled. Here a second 
command level is established. The first command level, and the program itself, 
have been suspended, but nothing has been thrown out. 



At this point further commands could be issued. The start command would 
cause the program to resume execution, and the stack to revert to the state 
illustrated in Figure 5-1b. The release command would cause the stack frame 
(and hence the execution state) of the program to be discarded, and the stack to 
revert to the state depicted in 5-1a. 



Note that it would be possible at the second command level (Figure 5-1c) to 
invoke the same program called at the first command level. 



Figure 5-2 illustrates several of the states of the stack during execution 
of a program consisting of several subprograms. The call/return sequence depicted 
is : 

Program A calls program B 
Program E calls program C 
Program C returns to B 
Program B calls program D 
Program D returns to B 
Program B returns to A 

Program A returns to command processor 



These diagrams illustrate the behavior of four separately compiled programs, 
each allocated a new- stack frame every time it is called: 
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Figure 5-2. Allocation of Stack Frames 
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(a) User at command level. 

(b) A is invoked and gets stack frame, in which automatic variables are 
allocated and initialized. 

(c) A calls B. B gets stack frame, in which automatic variables are allocated 
and initialized. 

(d) B calls C, C gets stack frame, in which automatic variables are allocated 
and initialized. 

(e) C returns to B, the stack frame for C is discarded, and storage is 
released . 

(f) B calls D, D gets stack frame, in which automatic variables are allocated 
and initialized. 

(g) D returns to B, the stack frame for D is discarded, and storage is 
released . 

(h) B returns to A, the stack frame for B is discarded, and storage is 
released . 

(i) A returns to command level. All program-specific automatic storage 
has been released. 



Automatic storage is storage which stays around only for the life of a 
program. Static storage is storage which stays around for the life of a process, 
or is retained across processes. 

If an unexpected error occurs (or you press the QUIT button), the system 
will save the current environment, mark the stack at its current level, and push 
a frame onto the stack for a new activation of the command processor. 



The new activation of the command processor accepts commands just as the 
original one did. It is possible to restart the suspended program, or to discard 
the saved environment, or to use one of the Multics debugging tools to examine 
the saved environment. 



The release command causes the command processor to return to its own previous 
activation, and discard the intervening stack contents. The programs whose stack 
contents have been discarded cannot be resumed or examined after the stack has 
been released. 



The start command causes the command processor to attempt to continue execution 
of the suspended program at the point of interruption. Depending on the nature 
of the error, and what has been done since the error occurred, the restart 
attempt may or may not succeed. Programs may always be restarted after a QUIT, 
but only seldom after an error. If the program cannot be restarted, the error 
message will usually be repeated. An unsuccessful attempt to restart a program 
is usually harmless. 



If you would like to examine the stack history of your process in detail, 
try using the trace__stack (ts) command, described in the MPM Commands. 



PROBE 



The probe (pb) command can be used to examine the saved stack and the 
current state of suspended programs. (Remember that a program which makes a 
call to another program is suspended just as a program which makes an error is 
suspended, except that a program which makes a call can always be resumed.) 
Probe can print the values of program variables and arguments, as well as reporting 
the last program location to be executed. 



The use of probe is shown here in a series of examples, which make use of 
the following program, blowup.pl! . This program has an illegal reference to the 
array "a", and the subscriptrange condition occurs when it is run. Since 
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subscriptrange checking is disabled by default in PL/I, the error manifests 
itself as an out_of_bounds condition instead of a subscriptrange. (In practice, 
it is recommended that PL/I programmers* enable such conditions as subscriptrange.) 
Although this error is easy to spot, the behavior of the program is typical of 
other, harder to spot errors. 



! print blowup. pl1 




blowup . p 1 1 


04/17/80 1332.0 mst Thu 


blowup: procedure; 




del j 


fixed binary; 


del a (10) 


fixed binary; 


del sum 


fixed binary; 


a (*) = 1 ; 




rin i - -1 to -100000 hv 


- 1 • 


sum = a ( j) ; 




end ; 




end blowup; 




r 13: 32 0. 1 10 20 




! p!1 blowup -table 




PL/I 




r 13:32 0.675 174 





The program is compiled with the -table control argument. This action 
causes a symbol table to be created, and stored with the program in the executable 
object segment. The information it contains can be used by the Multics debugging 
aids. A symbol table should always be created while debugging, so that errors 
may be found more easily. 



! blowup 

Error: out_of_bounds at >udd>Pro j A>MacSissle>blowup i 24 (line 9) 

referencing stack__4 1 777777 (in process dir) 

Attempt to access beyond end of segment, 
r 13:32 0.228 32 level 2 



The program is invoked by typing its name. It takes an 'out-of-bounds 1 
fault, because the subscript used in the reference to array "a" is invalid. The 
program does not use PL/I subscriptrange checking, so it attempts to calculate 
the address of the (nonexistent) element of "a" referenced. The resulting address 
does not exist, so the fault occurs. 

This message shows the name of the error condition, the pathname of the 
program, the octal location in the object segment where the error occurred, the 
line number, and an additional message about the error. If blowup was a FORTRAN 
program, the pathname would look like this: >udd>Pro j A >MacSissle>blowup$main_, 
blowup being the name of the segment and main_ the name of the program entry 
point. This is because every FORTRAN program has a "main" program entry point 
and Multics uses this as part of its name. If the program had not included a 
symbol table, the line number would not have been part of the message. 



! probe 

Condition out__of_bounds raised at line 9 of blowup (level 7). 
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MacSissle invokes the probe command. Probe looks for the program which 
caused the trouble, and prints a message about the most recent error found in 
MacSissle's process. The word "level" here refers not to command processor 
level, but to the number of programs saved on the stack. The error occurred in 
blowup, which was the seventh program on the stack. 



The stack is displayed by the "stack" request. This request shows every 
program on the stack, in the order invoked. There will always be unfamiliar 
programs on your stack. You can just ignore them—they are for handling errors, 
processing command, etc. The numbers on the left show the order of activation. 
The entry for blowup shows the source line number corresponding to the last 
location executed, and the name of the error that occurred. The line number can 
be determined because blowup was compiled with a symbol table. The other programs 
have no symbol table, so the display shows the octal offset of the last instruction 
executed • 



source 

sum = a ( j ) ; 



Using the "source" request, the source statement for line 9 is displayed. 
This is the line that was being executed when the error occurred. More precisely, 
the error occurred executing the object code corresponding to this source line. 



! value j 

j = -2689 
! symbol a, 

fixed bin (17) automatic dimension (10) 
Declared in blowup 



The value of the variable "j" is displayed with the "value" request. This 
request takes as its argument the name of a variable 5 and prints the value of 
the variable. (Note that a program must be suspended for you to look at its 
automatic variables.) Next, the "symbol" request is used, to show the attributes 
of "a." 



! position 8 



! stack 



13 
12 
1 1 
10 

Q 

,/ 

8 
7 
6 
5 

3 
2 



readjust ! 13^00 

command processor^ i 1 030 1 

abbrev_T7507 

re leasers tack ! 7355 

unclaimed__signal 12 4512 

wall! 4410 

blowup (line 9) 

read_list ! 13^00 

command processor^' 10301 

abbrev_T7507 

listen_!7355 

process_overseer ! 35503 

user init admin T40100 



out of bounds 



do j = -1 to -100000 by -1 ; 
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The "position" request is used to examine different lines of the program, 
in this case the line before the one that caused the hang. This request can 
also be used to examine different programs on the stack. For example, to look 
at the abbrev program on level 4, MacSissle could type "position level 4". 
However, she would most likely get the answer "probe (position): Cannot get 
statement map for this procedure," which means that the program was not compiled 
with the -table option. (Most system commands have -table omitted, to save 
space. ) 



! quit 

r 13:33 1.080 129 level 2 



The last probe request used is "quit," which exits probe, and returns to 
command level. MacSissle is still at command level two, and the program is 
still intact. The next command typed is the release command, which discards the 
saved frames, returning to level one. 



! release 

r 13:33 0.057 16 



Unlike interactive programs like read_mail, probe doesn't prompt you for 
requests. If you're not sure whether probe is listening, type a dot, and probe 
will respond with "probe 5.2" (or whatever the version number is) if it is 
there . 



Probe has many more features than there is room to present here. It should 
still be useful to you even if you don't use the other features, but to learn 
about them you can use the " list_request s" request, which tells you the name of 
every probe request, and the "help" request, which tells you about probe requests 
and also about probe itself. For example, you can type "help value" to find out 
about the "value" request, or "help help" to find out about "help". 



Another debugging tool which you may find useful is the trace command, 
which allows you to monitor all calls to a specified set of external procedures. 
Full descriptions of the probe and trace commands are available in the MPM 
Commands . 
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SECTION 6 



A PERFORMANCE MEASUREMENT TOOL 



After a program is written and debugged, it is often desirable to increase 
its efficiency. Multics provides performance measurement tools which identify 
the most expensive and most frequently executed programs in a given collection. 
Within these crucial programs, the most costly lines are found by using the 
profile facility. 



To use the profile facility, the first thing you have to do is compile your 
program with the -profile control argument. This control argument causes the 
compiler to generate special code for each statement, recording the cost of 
execution on a statement-by-statement basis. Then, after executing your program 
many times, you can use the profile command to look at its performance statistics. 



The example that follows shows the use of profile with a very small sample 
program to be used as a subroutine: 



prime_: procedure ( trial_prime) returns (bit (1) aligned); 

declare trial_prime fixed binary (35) parameter; 

declare trial_factor fixed binary, 

last__factor fixed binary; 

declare (mod, sqrt) builtin; 
last_factor = sqrt ( trial_prime) ; 
do trial_factor = 2 to last_factor; 

if mod (trial_prime, tr ial_factor ) = 0 
then return ("0"b); 

end; 

return (»1"b); 
end prime ; 



This subroutine cannot be called directly from command level, since only 
programs whose arguments are nonvarying character strings may be called directly. 
It is to be used with other programs. To test it, a simple command is written 
which accepts one argument, converts it to binary, and calls the prime_ subroutine. 
The testing command is called test_prime. It is not shown here. 



! pl1 prime__ -profile 
PL /I 

r 17:44 0.699 140 

! test_prime 3 
3 is a prime, 
r 17:44 .110 23 
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First, the prime_ subroutine is compiled using the -profile control argument. 
Next, the test__prime command is invoked with the argument "3"- Test_prime converts 
the 3 to binary, and calls the prime_ subroutine with it. 



! discard_output "test_prime ([index_set 500])" 
r 17:45 5. 103 54 



To evaluate the performance of the subroutine, several hundred calls to it 
should be made, over a wide range of values. The next command line invokes 
test__prime 500 times, with values from 1 to 5C0. The index__set active function 
returns the numbers from 1 to 500, and the parentheses invoke test_prime once 
for each value. 



The output from the program is not interesting, so the discard_output (dco) 
command is used. This command causes output from the program to be discarded, 
instead of printed on the terminal. 



! profile prime__ 

Program: prime_ 
LINE STMT COUNT COST STARS OPERATORS 



6 1000 34000 **** fx1_to_fl2, dsqrt, fl2_to_fx1 

7 1000 3000 

7 4ine 13254 *** 

8 4218 59052 **** mod_fx1 
Q 800 8800 ** return 

10 3418 6836 ** 

11 200 2600 return 



Totals: 15054 127542 



r 17:46 O.368 51 



While the program was run, performance statistics were saved. Now the 
profile command is used to display those statistics. For each line, it displays 
the total times executed, an estimate of the cost, and the PL/I operators used. 



Note that some statements (those in the loop) were executed more than others. 
The COST for a statement is the product of the number of instructions for the 
statement and the number of times the statement was executed. This cost does 
not take into account the fact that some instructions are faster than others, or 
the time spent waiting for missing pages (page faults). The STARS column gives 
a rough indication of the relative cost of each statement. 

The names of the PL/I operators used are also given. The operator fx1_to_fl2 
is used to convert the fixed point number to float, so that its root may be 
taken. The dsqrt operator takes the square root. Finally, the operator fl2__to_fx1 
converts the result back to integer. The PL/I mod builtin is implemented by the 
mod_fx1 operator. These operators are the most expensive things in the program. 
Occasionally a program can be rewritten to not require expensive operators. 
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' nrof"Me nrime —sort 


cost -first 5 






J. 1 CI ll! • [./ 1 








LINE STMT COUNT 


COST STARS 


OPERATORS 




8 4218 


59052 **** 


mod fx1 




6 1000 


34000 **** 


fx1 to fl2, dsqrt, 


fl2 to fxl 


7 4418 


13254 *** 






9 800 


8800 


return 




10 3418 


6836 ** 






Totals: 15054 


127542 






r 17:46 0.205 49 








When profiling large 


programs, it 


is usually desirable 


to look only at the 



most expensive lines, since they are the only ones of interest. The profile 
command can be instructed to sort the lines by cost, and display the five most 
costly lines in order. 



The profile command can also be instructed to produce a source language 
type of listing with performance statistics adjacent to each source line. Figure 
6-1 shows MacSissle using the profile command with the -list control argument to 
produce such a listing for the eompute_sum program. Note that when -list is 
used, the profile command produces a segment with the same name as the program, 
but with a suffix of "pfl". (Note also that MacSissle has again set her ready 
message to read "Karen is here".) 



More detailed records of execution are available if you compile your program 
with the -long__profile control argument. When this is done, the program samples 
the Multics clock before every instruction, so the total time per statement is 
available to the profile command. The performance data from a program compiled 
with -long_prof ile is displayed with the profile command. For further information, 
see the MPM Commands description of profile. 
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i oil compute. flufl -profile 
PL/I 

Karen is here 

! compute.sum 
Karen is here 

I profile conpute.sum -list 
Karen 1s here 

I print co^put c.suw.rf 

co^pute.su^.of 1 ns/oi/*i U?6.b edt Frl 



Profile listine of >udd> ? roj A> v acS1 ss 1 e>cowpute.9u^.o] 1 
Date: 05/01/Pl U?4.7 edt FM 
Total count: 7 Total cost; 107 



COUNT 



?0 *** 



CQ*T STA D S LTNF 
1 

? 
3 

6 
7 



10 
11 
1? 
1* 
14 
1? 
16 
17 
1* 
19 
2" 
21 
2? 
2* 
2a 
2? 
26 
27 
2* 
2* 
30 
31 
3? 
3? 
3 a 
35 
36 
37 



15 *** 



S9 *★** 



as **** 

?6 *** 
10 *+ 



co^out^.su'": proc cations Twain)? 

/* this orograw computes the sum of three 1 to 6 digit numbers read from an 
incut filer then writes the answer to an outout file */ 



Hec 1 are 



in_file stream *ile# 
out.fil* stream file* 
flrst.no *ixe* binary (?0)r 
seconrf.no fixed blnerv (20)* 
tnira.no fixee* binary (?0)p 
th e _sum fixed pinery (2>0* 



/* the Input file */ 
✓* the outout file */ 
/* the first number */ 
/* the second number *t 
/* the third number */ 
/* the answer */ 



/* oren the *iles */ 



ooen f1l^ fin. file) Inout, 

file Cout.f1l<?) outout; 

/* qet the three numbers fro* th* InDut file */ 

oet *ile (In.file) list (fir3t.no# second.no* th1rd.no); 
/* ado the" 1 up */ 

the-su* = first_no + s*cond_no + third.no; 
/* put the answer 1n the outout file */ 

out file (out. file) list (the.sum)f 

/* close t^e files */ 

close file (in.fll*), 
fil* f out. file): 

e^d comrute.sum? 



Figure 6-1. Use of profile Command With -list Control Argument 
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SECTION 7 



ABSENTEE FACILITY 



A common programming pattern is to develop a program online, using debugging 
tools and trying a variety of test cases interactively to check on a program's 
correctness. After the program is working, you may wish to do a large "production" 
run. Since the production run may produce a large amount of output or take a 
long time, you may not wish to wait at your terminal for the results. Production 
runs on Multics are best done using absentee jobs , which are somewhat analogous 
to batch jobs on other systems. 



An absentee job runs in an environment similar to that of an interactive 
user. In other words, an absentee job uses Multics in much the same way that a 
person does. It logs in to your home directory, and runs your start_up.ec, if 
any. This must be kept in mind, both when writing a start__up.ec and when submitting 
an absentee job. If you forget that your absentee job will run your start_up.ee, 
you may discover that it has stolen your messages or tried to read your mail. 
If you assume that your absentee job will log in to the directory from which you 
submitted it, you may discover that it has run the wrong version of your program. 



A big difference between an absentee job and an interactive user is that an 
absentee job is not associated with a terminal. Its input comes from a file, 
and its output goes to a file. (In an absentee process, the I/O switches are 
attached to the input and output segments, instead of the terminal.) 



An absentee input file, or control file , is a segment with the suffix 
"absin". At its simplest, it is just a collection of commands to be executed. 
The language used in an absentee job is the same as that used in exee_eoms. It 
is a superset of the command language. You must anticipate any responses or 
commands you must give ahead of time, and put all of this data into your control 
file. 



An absentee job is submitted by supplying the name of the absin file to 

the enter_abs__request (ear) command. The absin file is not copied. It stays 

absentee job. You must not, for example, edit a file it is using, or recompile 
a program it is running. 



The absentee job is placed in a queue and run as "background" to the normal 
interactive work of the system. This technique allows the system to utilize its 
resources most effectively, by keeping a queue of jobs that can always be run, 
and delayed for serving interactive users. For these reasons, the charging rate 
for absentee jobs is normally substantially lower than for interactive work. 



Output from an absentee job goes into a file whose name is the same as the 
absin segment, but with the suffix "absout" instead of "absin". When the job 
completes, you may print this absout segment. Figure 7-1 illustrates the differences 
between interactive usage and absentee usage. 



7-1 



AG90-03 




ABSENTEE 
PROCESS 




COMMANDS 


ABSIN 




FILE 



RESPONSES 
FILE I/O 



DATA 
FILE 



ABSOUT 
FILE 



Figure 7-1- Interactive vs Absentee Usage 
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Suppose MacSissle has written a FORTRAN program which figures square roots. 
The program resides in her directory of FORTRAN programs, and she would like to 
compile and run it absentee. The first thing she does is create a segment 
called compile_run .absin . 



cwd >udd>ProjA>MacSissle>fort_progs 

fort ran square_root . f ortran -list 

dprint -dl square_root . list 

square_root 

dprint filelO 

logout 



Then she types this command line: 

! enter_abs__request compile_run 

Her absentee job is submitted. When it runs, it changes to the proper working 
directory, compiles the program and produces a listing segment, prints the listing 
segment on the line printer and deletes it, runs the program, prints the output 
file "filelO" on the line printer, and finally, logs out. 



To run this same absentee job via remote job entry, MacSissle would put the 
statements shown above on cards instead of in a segment. Then she would surround 
her cards with control cards and put the deck in a card reader. Her absentee 
job would be executed automatically. 



The format of a card deck for remote job entry is shown below: 



++RJE DECK_NAME PERSON_ID PROJECTED 
++PASSWORD PASSWORD 

++AIM ACCESS CLASS OF ABSENTEE PROCESS 

++R JECONTROL CONTROL ARGS TO THE EAR COMMAND 

++R JEARGS ARGUMENTS FOR THE ABSENTEE PROCESS 

++EPILOGUE COMMAND 

++FORMAT PUNCH_FORMAT MODES 

++INPUT 



(user absentee file) 



The three cards required as a minimum are the first, which is an identifier 
card, the second, which is a password card, and the last, which signals the end 
of control input 



For another example, suppose MacSissle wants to use the prime_ subroutine 
discussed in Section 6 to check the prime-ness of the first five integers, and 
she wants to use the absentee facility to do it. Remember that prime_ is called 
by test_prime, and that the index_set active function can be used to return a 
set of numbers. 
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qedx 
a 

test_prime ( [ index__set 5]) 
\f 

w test5.absin 

q 

r 16:40 0,218 39 



MacSissle uses the Qedx editor to create her absin file. 



! enter_abs_request test5 -notify 
ID 210805.1; 5 already requested 
r 16:41 0.450 63 



Multics confirms her submission, giving the request id and the number of 
previously submitted jobs in the absentee queue. Often, many of these jobs may 
be "deferred", which is to say, they will not be run until a later time. Thus, 
"5 already requested" doesn't necessarily mean that five jobs must be run before 
MacSissle's job will run. 



From Initializer. SysDaemon (absentee) 04/21/80 1641.4 mst Mon: 
Absentee job >udd>Pro jA>MacSissle>test5 . absin 210805.1 
logged in. 



MacSissle used the -notify control argument on her ear command, so the 
system sends her a message when her job logs in. 



! who -absentee 

Absentee users 3/9 
JQUser.ProjB* 
TSmith.ProjA* 
MacSissle. Pro j A* 
r 16:42 0.272 22 



MacSissle uses the who command to print a list of all absentee jo^s. It 
shows that there are three already running, and that a total of nine can run at 
one time. Absentee users are identified by the asterisk after their project. 



From Initializer. SysDaemon (absentee) 04/21/80 1643.1 mst Mon: 
Absentee job >udd>ProjA>MacSissle>test5 . absin 210805.1 
logged out. 



The system also sends her a message when her job logs out. 
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! print test5.absout 

test5. absout 04/21/80 1643.6 mst Mon 

Absentee user MacSissle ProjA logged in: 04/21/80 1641.4 mst Mon 
r 16:41 2.364 55 

test_prime ( [index_set 5j) 

1 is a prime 

2 is a prime 

3 is a prime 

4 is not a prime 

5 is a prime 

r 16:42 0. 198 20 

abs_io__: Input Stream exhausted. 

Absentee user MacSissle ProjA logged out 04/21/80 1643.1 mst Mon 
CPU usage 3 sec, memory usage 1.0 units 



MacSissle f s job is done, so she prints the absout segment. 



With more advanced use of the absentee facility, you can also supply arguments 
to be substituted inside the absentee control segment, make absentee job steps 
conditional, delay absentee work until a chosen time, and develop a periodic 
absentee job which is run, say, once every two days. 



The next example shows how absentee jobs can accept arguments. 



! print prime. absin 




prime. absin 


04/21/80 1655.7 mst Mon 


test_prime ([index__set &1]) 




r 16:55 .110 19 





This absin segment accepts one argument. The character string "&1 n is 
replaced by the argument wherever it occurs. MacSissle tests it by invoking it 
as an exec_com. In order to use the absin segment as an exec_com, it must have 
a name with the suffix !l ec" added to it. 



! add name prime. absin prime. ec 
r 1^:56 0. 100 5 

! exec_com prime. ec 2 

test__prime ([index_set 2]) 

1 is a prime 

2 is a prime 

r 17:00 0.210 30 



MacSissle invokes the exec_com with the argument 2. As it runs, it prints 
the commands in the file. The argument mechanism seems to work, so she submits 
an absentee job. 
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! enter__abs_request prime. absin -arguments 100 
ID: 221023-4; 6 already requested, 
r 17:05 0.273 50 



Here, the argument 100 is passed to the absentee job. MacSissle goes about 
other business while the request runs. 



A common problem for many users is an absentee job that blows up unexpectedly 
because it is asked an unanticipated question, and the user has not provided an 
appropriate answer. For example, a job may be asked, "Do you wish to quit?" It 
can try to use its next command for an answer, but it will be told to "Please 
answer yes or no*" At this point, the job will probably die. 



Suppose MacSissle has set up a daily absentee job that reads her mail. Her 
absin segment, called mail. absin, looks like this: 



enter_abs__request mail -time "07:00" -notify 

read_mail 

print all 

quit 

dprint -delete mail.absout 



MacSissle types the command line 



! enter_abs_request mail -time "07:00" -notify 

once. Her absentee job submits a request for the next absentee job, then reads 
her mail. Once in the read_mail request loop, it asks that all of her mail be 
printed, then quits out of the loop. Finally, it dprints her absout segment. 



This job seems like it should work fine. But what will happen if MacSissle 
doesn't have any mail? The request to read her mail will return the answer, 
"You have no mail". Then the request to print all of her mail will return the 
answer, "Segment all not found". The request to quit will return a similar 
answer. So, the job may not die in this case, but it will give MacSissle some 
unexpected results* To avoid this problem, MacSissle can change her absin segment 
to look like this: 



enter_abs__request mail -time "07:00" -notify 
read_mail -request "print all; quit" 
dprint -delete mail.absout 



Now, if she has no mail, she'll just get the answer, "You have no mail", 
which is what she wants. 



For further information on absentee jobs, see the MPM Commands manual 
descriptions of the enter_abs_ request and exec_com commands. See also the 
descriptions of the pl1_abs, cobol_abs, and fortran_abs commands, which invoke 
language compilers in absentee jobs. 
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SECTION 8 



REFERENCE TO COMMANDS BY FUNCTION 



All of the Multics commands described in the MPM Commands are arranged here 
according to function and are briefly described. The Multics command repertoire 
is divided into the following 17 groups: 



Access to the System 

Storage System, Creating and Editing Segments 
Storage System, Segment Manipulation 
Storage System, Directory Manipulation 
Storage System, Access Control 
Storage System, Address Space Control 
Formatted Output Facilities 

Language Translators, Compilers, and Interpreters 
Object Segment Manipulation 

Debugging and Performance Monitoring Facilities 

Input/Output System Control 

Command Level Environment 

Communication Among Users 

Communication with the System 

Accounting 

Control of Absentee Computations 
Miscellaneous Tools 



Many commands can perform more than one function, so they are listed in 
more than one group. 



Detailed descriptions of these commands, arranged alphabetically rather than 
functionally, are given in the MPM Commands. In addition, many of the commands 
have online descriptions, which you may obtain by invoking the help command. 



ACCESS TO THE SYSTEM 



dial 

echo 
enter 
enterp 
hangup 

hello 

login 

logout 

modes 

slave 



connects an additional terminal to an existing 
process 

sets terminal into echoplex mode before login 
connects an anonymous user to the system 

(used at dialup only) 
terminates communication between terminal and 

Multics 

repeats greeting message printed when terminal 

is first connected 
connects registered user to the system (used 

at dialup only) 
disconnects user from the system 
sets terminal modes before login 
changes service type of channel from login to 

slave for duration of connection 
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terminal_type sets terminal type before login 

MAP tells system user is attempting to gain access 

from terminal whose keyboard generates only 

uppercase characters 
029 and 963 tells system whether user is attempting to 

gain access from device similar to EBCDIC 

or Correspondence code IBM Model 2741 



STORAGE SYSTEM, CREATING AND EDITING SEGMENTS 



ad just_bit__count 

canonicalize 

compare__ascii 
compose 

edm 
emacs 

indent 

merge_ascii 
qedx 

set_bit_eount 
ted 



sets bit count of a segment to last nonzero 

word or character 
ensures that contents of a segment are in 

canonical form 
compares ASCII segments, reporting differences 
composes formatted documents for production 

on various devices, including terminals 

and line printers 
allows inexpensive, easy editing of ASCII 

segments 

enters the Emacs text editor, which has a large 
repertoire of requests for editing and 
formatting text and programs 

indents a PL/I source segment to make it more 
readable 

merges two or more related ASCII text segments 
allows sophisticated editing, including macro 

capabilities 
sets the bit count of a segment to a specified 

value 

used to create and edit ASCII segments; can 
do many kinds of text processing 



STORAGE SYSTEM, SEGMENT MANIPULATION 



ad just_bit_eount 

archive 
archive_table 

compare 

compare_ascii 
copy 

copy_file 
create 

damaged_sw_off 

damaged_sw_on 

delete 

link 



merge_ascii 



sets bit count of a segment to last nonzero 

word or character 
packs segments together to save physical storage 
returns the names of specified archive 

components in specified archive segment 
compares segments word by word, reporting 

differences 

compares ASCII segments, reporting differences 
copies a segment or multisegment file and its 

storage system attributes 
copies records from an input file to an output 

file 

creates an empty segment 

resets damaged switch off for segments 

sets damaged switch on for segments 

deletes a segment or multisegment file and 

questions user if it is protected 
creates a storage system link to another 

segment, directory, link, or multisegment 

file 

merges two or more related ASCII text segments 
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move 

set_bit_eount 

sort_seg 

tape__archive 



truncate 

unlink 

vf ile_ad just 

volume_dump_switch__of f 

volume_dump switch on 



moves segment or multisegment file and its 
storage system attributes to another 
directory 

sets the bit count of a segment to a specified 
value 

sorts ASCII segments according to ASCII 

collating sequence 
performs a variety of operations to create 

and maintain a set of files on magnetic 

tape 

truncates a segment to a specified length 
removes a storage system link 
adjusts structured and unstructured files 
turns off the specified volume dump switch of 
a segment 

turns on the specified volume dump switch of 
a segment 



STORAGE SYSTEM, DIRECTORY MANIPULATION 



add__name 

cancel_retrieval__request 

copy_dir 

create__dir 
delete__dir 

delete_name 

enter__retrieval_request 
link 

iist_retrieval_requests 
list 

move_dir 
rename 

safety_sw_off 

safety_sw_on 

status 

tape_archive 

unlink 

vf ile__status 

v o 1 um e__dump_s wi t c h_o f f 

volume dump switch on 



adds a name to a segment, directory, link, or 

multisegment file 
deletes request for a volume retrieval that 

is no longer needed 
copies a directory and its subtree to another 

point in the hierarchy 
creates a directory 

destroys a directory and its contents after 

questioning user 
removes a name from a segment, directory, link, 

or multisegment file 
queues volume retrieval requests for specific 

segments, directories, multisegment files, 

and subtrees 
creates a storage system link to another 

segment, directory, link, or multisegment 

file 

lists retrieval requests in the retrieval daemon 
queues 

prints directory contents 

moves a directory and its subtree to another 

point in the hierarchy 
renames a segment, directory, link, or 

multisegment file 
turns safety switch off for a segment, 

directory, or multisegment file 
turns safety switch on for a segment, directory, 

or multisegment file 
prints all the attributes of an entry in a 

directory 

performs a variety of operations to create 
and maintain a set of files on magnetic 
tape 

removes a storage system link 

prints the apparent type and length of storage 

system files 
turns off the specified volume dump switch of 

a segment 

turns on the specified volume dump switch of 
a segment 
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STORAGE SYSTEM, ACCESS CONTROL 



check_iacl 

copy_acl 

copy_iacl_dir 

copy_iacl_jseg 

delete_acl 

delete_iacl_dir 

delete_iacl_seg 

list_accessible 

list_acl 

list_not_accessible 

list_iacl__dir 
list_iacl_seg 
print_auth_names 

set_acl 
set_iacl_dir 

set iacl seg 



compares segment ACLs with the initial ACL 
copies ACL from segment or directory 
copies a directory initial ACL 
copies a segment initial ACL 
removes an ACL entry 

removes an initial ACL for new directories 
removes an initial ACL for new segments 
lists segments and directories with a given 

access condition 
prints an ACL entry 

lists segments and directories to which user 

does not have a given access condition 
prints an initial ACL for new directories 
prints an initial ACL for new segments 
prints names of sensitivity levels and access 

categories for an installation 
adds (or changes) an ACL entry 
adds (or changes) an initial ACL for new 
directories 

adds (or changes) an initial ACL for new segments 



STORAGE SYSTEM, ADDRESS SPACE CONTROL 



add_jsearch_paths 
add_search_rules 
attach_lv 

change_default_wdir 

change_wdir 

delete_search_paths 

delete_search_rules 
detach_lv 

get_system_search_rules 

initiate 
list_ref_names 

new_proc 

print_default__wdir 
print_proc_auth 

print_search_paths 

print_search_rules 

print_wdir 
set_search_paths 

set_search_rules 
terminate 

walk_subtree 

where 



adds one or more search paths to the specified 
search list 

allows users to change (insert) search rules 
dynamically 

calls the resource control package to attach 

a logical volume 
sets the default working directory 
changes the working directory 
allows user to delete one or more search paths 

from specified search list 
allows users to delete current search rules 
detaches logical volumes attached by the 

resource control package 
prints definitions of site-defined search rule 

keywords 

adds a segment to the address space of a process 
prints all names by which a segment is known 

to a process 
creates a new process with a new address space 
prints name of default working directory 
prints access authorization of the current 

process and current system privileges 
prints the search paths in the specified search 

list 

prints names of directories searched for 

segments referenced dynamically 
prints name of current working directory 
allows user to replace search paths contained 

in specified search list 
allows users to modify search rules 
removes a segment from the address space of a 
process 

executes a command line in all directories 

below a specified directory 
uses current search rules to locate and print 

pathname of a segment 
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where search_paths 



returns absolute pathname(s) of entryname when 
search list name and entryname are specified 



FORMATTED OUTPUT FACILITIES 



cancel__daemon_request 
compose 



dprint 
dpunch 

dump_segment 
list_daemon__requests 
move_daemon_request 
overlay 



print 



cancels a previously submitted daemon request 
composes formatted documents for production 

on various devices, including terminals 

and line printers 
queues a segment or multisegment file for 

printing on the high-speed printer 
queues a segment or multisegment file for card 

punching 

prints segment contents in octal, ASCII, or 
EBCDIC 

prints list of print and punch requests 

currently queued 
moves a request from one I/O daemon queue to 

another 

reads several ASCII segments and writes on 
user_output I/O switch output that is the 
result of superimposing print -positions 
from each segment 

prints an ASCII segment 



LANGUAGE TRANSLATORS, COMPILERS, AND INTERPRETERS 



apl 

basic 

bind 

cancel_eobol_program 

cobol 
cobol_abs 

create_data_segment 

display_cobol_run_unit 
expand_cobol_source 



fast 

format_cobol__source 

fortran 
fortran_abs 

indent 

lisp 



PH 

pl1_abs 
profile 

run cobol 



invokes the APL interpreter 
compiles BASIC programs 

packs two or more object segments into a single 

executable segment 
cancels one or more programs in the current 

COBOL run unit 
compiles COBOL programs 

submits an absentee request to perform COBOL 

compilations 
translates a create_data_segment source program 

into an object segment 
displays the current state of a COBOL run unit 
translates COBOL source program containing COPY 

and REPLACE statements to equivalent source 

program not containing these statements 
allows user to enter FAST subsystem 
converts free-form COBOL source to fixed-format 

COBOL source 
invokes the site's "standard" FORTRAN compiler 
invokes the site's "standard" FORTRAN compiler 

in an absentee job 
indents a PL/I source segment to make it more 

readable 

enters interactive Lisp subsystem, where Lisp 
forms can be typed at user's terminal and 
evaluated 

compiles PL/I programs 

invokes the PL/I compiler in an absentee job 
prints information about execution of 

individual statements within program 
executes a COBOL run unit in a main program 
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set__cc 

set_fortran__common 
stop_cobol_run 



sets carriage control transformation for 

FORTRAN files 
initializes common storage for a FORTRAN run 
terminates the current COBOL run unit 



OBJECT SEGMENT MANIPULATION 



archive packs segments together to save physical storage 

archive_table returns the names of specified archive 

components in specified archive segment 
bind packs two or more object segments into a single 

executable segment 

date__compiled prints date and time compiled and compiler 

identifier for object segments 



DEBUGGING AND PERFORMANCE MONITORING FACILITIES 



attach_audit 

change_error_mode 

cumulative_page_trace 
debug 

display__audit_file 

display_pi1 io__error 

dump_segment 

general_ready 
page__trace 

probe 
profile 

progress 

ready 

ready_of f 

ready_on 

reprint_error 

resolve_linkage_error 

trace 

trace stack 



sets up specified I/O switch to be audited by 

the audit_ I/O module 
adjusts length and content of system condition 

messages 
accumulates page trace data 
permits symbolic source language debugging 
displays the file produced by the audit_ I/O 

module 

displays diagnostic information about PL/I I/O 
errors 

prints segment contents in octal, ASCII, or 
EBCDIC 

allows user to format ready messages 
prints a history of system events within calling 
process 

permits program debugging online 

prints information about execution of 

individual statements within program 
prints information about the progress of a 

command as it is being executed 
prints the ready message: a summary of CPU 

time, paging activity, and memory usage 
suppresses the printing of the ready message 
restores the printing of the ready message 
reprints an earlier system condition message 
satisfies linkage fault after a process 

encounters a linkage error 
permits the user to monitor all calls to a 

specified set of external procedures 
prints stack history 



INPUT/OUTPUT SYSTEM CONTROL 



assign_resouree 
cancel_resource 

eancel_daemon__request 

close_f ile 
copy_cards 
copy_file 



assigns peripheral equipment to user 
cancels reservations made with the reserve 
command 

cancels a previously submitted print or punch 
request 

closes open PL/I and FORTRAN files 
copies card decks read by I/O Daemon 
copies records from an input file to an output 
file 
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diseard_output 

display_j>l1io__error 

dprint 

dpunch 

f ile_output 
io_call 

line_length 

list_daemon_requests 

list__resource__types 

list__resources 
print 

print_attaeh__table 

print_request__types 
reserve_resource 

tape_archive 



unassign_resource 
vfile_ad just 
vfile status 



executes a command line while temporarily 
suppressing output on specified I/O 
switches 

displays diagnostic information about PL/I I/O 
errors 

queues a segment or multisegment file for 
printing on the high-speed line printer 

queues a segment or multisegment file for card 
punching 

directs terminal output to a file 
allows direct calls to input/output system 
entries 

allows users to control maximum length of output 
lines 

prints list of print and punch requests 

currently queued 
prints a list of all resource types described 

in a resource type description table (RTDT) 
lists peripheral equipment assigned to user 
prints an ASCII segment 

prints list of current input/output system 

switch attachments 
prints available I/O Daemon request types 
reserves resource(s) for use by the calling 

process 

performs a variety of operations to create 
and maintain a set of files on magnetic 
tape 

unassigns peripheral equipment assigned to user 
adjusts structured and unstructured files 
prints the apparent type and length of storage 
system files 



COMMAND LEVEL ENVIRONMENT 



abbrev 

add_search_j>aths 

add_jsearch_rules 

answer 
attach__audit 

change_default_wdir 
change_error_mode 

change_wdir 
delete_search paths 

delete_search_rules 

detach_audit 

display_audit_file 

do 

exec_com 
fast 

file output 



allows user-specified abbreviations for command 
lines or parts of command lines 

adds one or more search paths to the specified 
search list 

allows users to change (insert) search rules 
dynamically 

answers questions normally asked of the user 
sets up specified I/O switch to be audited by 

the audit_ I/O module 
sets the default working directory 
adjusts length and content of system condition 

messages 
changes the working directory 
allows user to delete one or more search paths 

from specified search list 
allows users to delete current search rules 
removes audit_ from specified switch 
displays the file produced by the audit_ I/O 

module 

expands a command line with argument 

substitution 
allows a segment to be treated as a list of 

executable commands 
allows user to enter FAST subsystem 
directs terminal output to a file 
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gcos 

general_ready 
get_system_search_rules 

if 

line_length 

memo 

new_jp>roc 

on 



print_default_wdir 
print_search_paths 

print search rules 

print_wdir 
program_interrupt 

ready 

ready_off 

ready_on 

release 

repeat_query 

reprint_error 
resolve_linkage_error 

run 



set_search_paths 

set_search_rules 
set_tty 

start 

stop__run 

where search paths 



invokes GCOS environment simulator to run single 

GCOS job in user's process 
allows user to format ready messages 
prints definitions of site-defined search rule 

keywords 

conditionally executes a command line 
allows users to control maximum length of output 
lines 

allows users to set reminders for later printout 
creates a new process with a new address space 
establishes handler for specified set of 
conditions, executes imbedded command line 
with handler in effect, reverts handler 
prints name of default working directory 
prints the search paths in the specified search 
list 

prints names of directories searched for 

segments referenced dynamically 
prints name of current working directory 
provides for command reentry following a quit 

or an unexpected signal 
prints the ready message: a summary of CPU 

time, paging activity, and memory usage 
suppresses the printing of the ready message 
restores the printing of the ready message 
discards process history retained by a quit 

or an unexpected signal interruption 
repeats the last query by the command_query_ 

subroutine 

reprints an earlier system condition message 
satisfies linkage fault after a process 

encounters a linkage error 
provides user with temporary, somewhat 

isolated, environment for execution of 

programs 

allows user to replace search paths contained 

in specified search list 
allows users to modify search rules 
prints and sets modes associated with user f s 

terminal 

continues process at point of a quit or an 
unexpected signal interruption 

effects abnormal termination of run-unit 
created by run command 

returns absolute pathname(s) of entryname when 
search list name and entryname are specified 



COMMUNICATION AMONG USERS 



accept_messages 

defer_messages 

delete_message 
immediate_messages 
print_mail 
print_messages 
read mail 



initializes the process to accept messages 
immediately 

inhibits the normal printing of received 
messages 

deletes messages saved in user's mailbox 
restores immediate printing of messages 
prints all messages in a mailbox 
prints any pending messages 

provides a facility for examining and 
manipulating messages 
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send_mail transmits a message to one or more recipients 

send_message sends message to specified user 

send_message_acknowledge sends message and acknowledges its receipt 

send_message_express sends message only if user will receive it 

immediately 

send_message_silent sends message but does not acknowledge its 

receipt 

who prints list of users and absentee jobs currently 

logged in 



COMMUNICATION WITH THE SYSTEM 



cancel_retrieval_request 

cheek_info_segs 

damaged_sw_of f 

damaged__sw_on 

help 

h o w_jn a n y _u s e r s 
enter_retrieval__request 

list_help 

list__retrieval_requests 
move__abs_request 
no_save__on_d is connect 
print_jnotd 
save__on_disconnect 
volume__dump_switch_of f 
volume_dump_switch_on 
who 



deletes request for a volume retrieval that 

is no longer needed 
checks information (and other) segments for 

changes 

resets damaged switch off for segments 

sets damaged switch on for segments 

prints special information segments 

prints the number of logged-in users 

queues volume retrieval requests for specific 

segments, directories, multisegment files, 

and subtrees 
displays names of all info segments pertaining 

to a given topic 
lists retrieval requests in the retrieval daemon 

queues 

moves a request from one absentee queue to 
another 

disables process preservation across hangups 

in user*s process 
prints the portion of the message of the day 

that changed since last printed 
reverses effect of no_save_on_disconnect 

command 

turns off the specified volume dump switch of 
a segment 

turns on the specified volume dump switch of 
a segment 

prints list of users and absentee jobs currently 
logged in 



ACCOUNTING 



get__quota 
move_quota 

resource usage 



prints secondary storage quota and usage 
moves secondary storage quota to another 
directory 

prints resource consumption for the month 
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CONTROL OF ABSENTEE COMPUTATIONS 



cancel__abs_jr*equest 

cobol__abs 

enter_abs__request 
fortran_abs 

how_many_users 
list_abs_requests 

move__abs_request 

pl1_abs 
runof f_abs 
who 



cancels a previously submitted absentee job 
request 

submits an absentee request to perform COBOL 

compilations 
adds a request to the absentee job queue 
invokes the site's "standard" FORTRAN compiler 

in an absentee job 
prints the number of logged-in users 
prints list of absentee job requests currently 

queued 

moves a request from one absentee queue to 
another 

invokes the PL/I compiler in an absentee job 
invokes the runoff command in an absentee job 
prints list of users and absentee jobs currently 
logged in 



MISCELLANEOUS TOOLS 



calc 

calendar 
canonicalize 

decode 
encode 

manage_volume_j?ool 

memo 

merge 

progress 

sort 



performs specified calculations 

prints a calendar page for one month 

ensures that contents of a segment are in 

canonical form 
deciphers segment, given proper coding key 
enciphers segment, given a coding key 
allows users to regulate use of a predefined 

set of volumes 
allows users to set reminders for later printout 
provides generalized file merging capability 
prints information about the progress of a 

command as it is being executed 
provides generalized file sorting capability 
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APPENDIX A 



USING MULTICS TO BEST ADVANTAGE 



You may, if you wish, treat Multics as simply a PL/I, FORTRAN, APL, BASIC, 
or COBOL machine, and contain your activities to just the features provided in 
your preferred programming language. On the other hand, much of the richness of 
the Multics programming environment involves use of system facilities for which 
there are no available constructs in the usual languages. To use these features, 
it is generally necessary to call upon library and supervisor subroutines. 
Unfortunately, a simple description of how to call a subroutine may give little 
clue as to how it is intended to be used. The purpose of this appendix is to 
illustrate typical ways in which many of the properties of the Multics programming 
environment may be utilized. 



When you choose a language for your implementation, you should carefully 
consider the extent to which you will want to go beyond your language and use 
system facilities of Multics which are missing from your language. As a well-known 
standard for completeness of that language (e.g., ANSI or IBM). However, in 
going beyond the standard languages, you will find that Multics supervisor and 
library routines are designed primarily for use from PL/I programs. This results 
from the fact that most of these routines are themselves implemented in PL/I. 
For example, if you plan to write programs which directly call the Multics 
storage system privacy and protection entries, in FORTRAN or BASIC, you have no 
convenient way to express such structures. Note that the situation is not hopeless, 
however. Programs which stay within the original language can be written with 
no trouble. Also, in many cases, a trivial PL/I interface subroutine can be 
constructed, which is callable from, say, a FORTRAN program, and goes on to 
reinterpret arguments and invoke the Multics facility desired. This is made 
possible by the Multics conventions which ensure that FORTRAN and PL/I programs 
can communicate. (For more information, see the MPM Subsystems Writers 1 Guide.) 
Using such techniques, almost any program a standard call is performed, the 
argument pointer is set to point at the originally prepared for another system 
can be moved into the Multics environment. 



The examples which follow show that the effect of the mapping together of 
the main memory and secondary storage environments can range from the negligible 
(programs can be written as though there was a traditional two-environment system) 
to a significant simplification of programs which make extensive use of the 
storage system. Here are seven brief examples of programs which are generally 
simpler than those encountered in practice, but which illustrate ways in which 
online storage is accessed in Multics. 
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Internal Automatic Variables. The following program types the word "Hello" 
on four successive lines of terminal output: 



a: 


procedure ; 




declare i fixed binary; 




do i = 1 to 4; 




put list ("Hello"); 




put skip; ) 




end; 




return; 




end a; 



The variable i is by default of PL/I storage class internal automatic ; 
in Multics it is stored in the stack of the current process and is available 
by name only to program a and only until a returns to its caller. It is 
declared binary for clarity: although the default base for the representation 
of arithmetic data is binary according to the PL/I standard, as well as in 
Multics PL/I, some other popular implementations have a decimal default. 
There is no need for decimal arithmetic in this program, and binary arithmetic 
is faster. 

Internal Static Variables. The following program, each time it is called, 
types out the number of times it has been called since its user has logged 
in: 



b: 


procedure ; 






declare j fixed binary 


internal static intial(O); 




j = j + i; 






put list (j, "calls to 


b."); 




put skip; 






return; 






end b; 





The variable j is of PL/I storage class internal static ; in Multics it 
is stored in b f s static section (discussed in Section 2) and is available 
by name only to program b. Its value is preserved for the life of the 
process, or until b is terminated (by the terminate command, recompilation, 
etc.), whichever time is shorter. The "initial" declaration causes the 
value of j to be initialized at the time this procedure is first used in a 
process. 
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External Static. Suppose you wish to set a value in one program and have 
it printed by some other program in the same process: 



c: 


procedure; 










declare z fixed 


binary 


external 


static ; 




z = 4; 








return; 










end c; 








d: 


procedure ; 










declare z fixed 


binary 


external 


static; 




put list (z); 










put skip; 










return; 










end d; 









In both programs, the variable z is of PL/I storage class external 
static ; in Multics it is stored in a particular segment where all such 
variables are stored, and is available to all procedures in a particular 
process, until the process is destroyed. External static is analogous to 
common in FORTRAN, but with the important difference that data items are 
accessed by name rather than by relative position in a declaration. Program 
d above could be replaced by the following FORTRAN program: 



integer n 
common /z/ n 
print, n 
end 



Multics calls such data items external variables . There are commands 
(for example, list_external_variables ) to list, reinitialize, and otherwise 
deal with all the external variables used by a process. Each variable 
which is accessed in this form generates a linkage fault the first time it 
is used. Later references to the variable by the same procedure in that or 
subsequent calls do not generate the fault. 

Direct Intersegment References. The following program prints the sum of 
the 1000 integers stored in the segment w: 



e: procedure; 

declare w$(1000) fixed binary external static; 
declare (i, sum) fixed binary; 

sum = 0; 
do i = 1 to hbound (w$,1); 

sum = sum + w$(i) ; 

end; 

put list (sum); 
put skip; 
return; 
end e; 



A-3 



AG90-03 



The dollar sign in the PL/I identifier "w$" is recognized as a special 
symbol by the PL/I compiler, and code for statement 6 is constructed which 
anticipates dynamic linking to the segment named w. Upon first execution, 
a linkage fault is triggered, and a search undertaken for a segment named 
w. If one is found, the link is snapped, and all future references will 
occur with a single machine instruction. The storage for array "w$ If i_s the 
segment w. 



If no segment named w is found, the dynamic linker will report an 
error to the user and return to command level. At this point, it is possible 
to create an appropriate segment named w, and then continue execution of 
the interrupted program, if such action is appropriate. 

6. Reference to Named Offsets. The following procedure calculates the sum of 
1000 integers stored in segment x starting at the named offset u: 



f : 


procedure ; 




declare x$u(1000) fixed binary external static; 




declare (i, sum) fixed binary; 




sum = 0; 




do i = 1 to 1000; 




sum = sum + x$u( i ) ; 




end; 




put list (sum); 




put skip; 




return ; 




end f; 



The difference between this example and the previous one is that segment 
x is presumed to have some substructure, with named internal locations 
(entry points). To initially create a segment with such a substructure, 
the compilers and assemblers are used, since information must be placed in 
the segment to indicate where within it the entry points may be found. 
Unfortunately, the PL/I language permits specification of such structured 
segments only for procedures, not for data. The create_data__segment 
subroutine can be used in conjunction with the create__data_segment (cdsT 
command to create such data segments from PL/I data structures passed to it 
as parameters. The create__data__segment command translates a CDS source 
program into a data segment (actually a standard object segment). A sample 
CDS source program, x.cds, is shown below: 



x: procedure; 

declare 1 x aligned, 

2 u(1000) fixed binary; 
declare create_data_segment_ entry (ptr, fixed binary (35)); 

(overhead required to utilize ereate_data__segment__) 

call create_data_segment_ <cds_args>; 

return; 

end x; 
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The ALM assembler can also be used to create a structured data segment, as 
shown by x.alm below: 



name x 
segdef u 
u: bss 1000 
end 



External Reference Starting With a Character String- In many cases, a 
segment must be accessed whose name has been supplied as a character string. 
In those cases, a call to the Multics storage system is required in order 
to map the segment into the virtual memory and to obtain a pointer to it. 
The following program uses the supervisor entry hcs_$make_ptr to perform a 
search for a segment of a given name, identical to that undertaken by the 
linker in the previous examples. 



g: procedure ( string) ; 

declare string character ( *) parameter; 

declare hcs_$make_ptr entry (pointer, character( *) , 

characterC *) , pointer, fixed binary(35)); 
declare null builtin; 
declare p pointer; 
declare ec fixed binary (35); 

declare hcs_$terminate__seg entry (ptr, fixed binary (1), 

fixed binary (35)); 
declare com__err entry options (variable); 
declare (i, sumT fixed binary; 
declare v(1000) fixed binary based(p); 
call hcs_$make_ptr (null (), string, Tlff , p, ec); 
if p= null then do; 

call com__err_ (ec, "g", "~a" , string); 

return; 
end; 

sum = 0; 

do i s 1 to 1000; 

sum = sum + p v(i) ; 
end; 

/* The segment should be terminated, since it was 

initiated */ 
call hcs_$terminate_seg (p, 0, (0)); 
return; 
end g; 



The PL/I null string value ( nw ) indicates that it is not a named entry 
point in the segment to which a pointer is wanted, but a pointer to its 
base. Perhaps the segment does not even have named entry points. The PL/I 
null pointer value (nullO ) and the zero passed by value ((0)) in the call 
to hcs_$make_ptr are relevant to its handling of error conditions and some 
of the parameters of the search for the segment. See the MPM Subroutines 
for a full description of the hcs_$make_ptr subroutine. 
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8. Reference to Segment Via Pathname. The following procedure finds a segment 
specified by an absolute or relative pathname given as an argument.. Most 
Multics commands accept pathnames and find the segments they are to operate 
on in this fashion. This procedure also adds all the numbers in the segment, 
obtaining the number of entries in the array by using the bit count of the 
segment . 



h: procedure (string) ; 

declare string ehar(*); 

declare expand_jpathname_ entry (char(*), char(*), char(*), fixed 
binary(35)); 

declare dn char(l68), en char(32), ec fixed binary(35); 
declare eom_err_ entryO options ( variable) ; 

declare hcs $initiate_count entry char(*), char ( * ) , char ( *) - fixed 

binary(27) , fixed binary(2), ptr, fixed binary(35)); 
declare null builtin; 
declare be fixed binary(2M); 
declare p ptr; 

declare nwords fixed binary; 

declare i fixed binary; 

declare sum fixed binary (35); 

declare w (nwords) fixed binary(35) based (p); 

declare hcs__$terminate__noname entry (ptr, fixed binary (35)); 

declare sysprint file; 

call expand__pathname_ (string, dn , en , ec ) ; 
if ec 0 then do; 
err: call com_err_ (ec , "h" ," ~a" , string) ; 
return; 
end; 

call hcs$initiate_eount (dn,en, ,be , 0, p ,ec) ; 
if p = null then goto err; 
nwords = divide (be , 36, 17, 0) ; 
sum = 0; 

do i = 1 to nwords; 

sum = sum + w(i) ; 
end; 

call hcs_$terminate_noname (p,(0)); 
put list (sum); 
put skip; 
end h; 



The expand_pathname__ procedure is a library subroutine which accepts a relative 
or absolute pathname and returns the directory name and entryname ready for use 
by supervisor entries such as hcs_$initiate_count . No search for the segment 
specified is undertaken in this case. Since the segment was initiated with a 
null reference name (third argument to hcs_$initiate_count ) , the procedure is 
responsible for terminating it as well. 



Further improvements to this procedure are possible. It lacks the ability 
to handle several common error cases; if no argument is supplied, for example, 
the program will malfunction. Code to handle this possibility should be included, 
as well as code to handle the possibility of a zero-length input segment, or the 
possibility of a fixed point overflow. 
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APPENDIX B 



A SIMPLE TEXT EDITOR 



The sample program discussed in this appendix is a printing-terminal text 
editor similar to, but simpler than, Edm. (See Appendix D for a description of 
Edm.) It is a typical example of an interactive program which makes use of the 
Multics storage system via the virtual memory. In overview, the editor creates 
two temporary storage areas, each large enough to hold the entire text segment 
being edited; copies the segment into one of these areas, so as not to harm the 
original; and then, as the user supplies successive editing requests, constructs 
in the other area an edited version of the segment. When the user finishes a 
pass through the segment, the editor interchanges the roles of the two storage 
areas for the next editing pass. When the user is done with the editor, the 
appropriate temporary storage area is then copied back over the original segment. 
This example is not intended to be a model for designing or implementing text 
editors, but rather, an illustration of the techniques used in interactive Multics 
PL/I programs, particularly commands. 



For this example, a program listing as produced by the PL/I compiler is 
used. The program itself is derived from the edm command of Multics, and it 
exhibits several different styles of coding and commenting, since it has had 
many different maintainers . 



The program listing is preceded by several pages of comments on the program. 
The comments appear in the same order as the item(s) in the program that they 
comment on. Where possible, they refer to line numbers in the program listing. 
Unfortunately, programs do not always invoke features in the best order for 
understanding, so the following strategy may be useful: as you read each comment, 
if its implications are clear and you feel you understand it, check it off. If 
you encounter one which does not fit into your mental image of what is going on, 
skip it for the moment. Later comments may shed some light on the situation, as 
will later reference to other Multics documentation. Finally, a hard core of 
obscure points may remain unexplained, in which case the advice of an experienced 
Multics programmer is probably needed. Be warned that the range of comments is 
very wide, from trivial to significant, from simple to sophisticated, and from 
obvious to extremely subtle. 



Finally, some comments provide suggestions for "good programming practice". 
Such suggestions are usually subjective, and often controversial. Nonetheless, 
the concept of choosing among various possible implementation methods one which 
has clarity, is consistent, and minimizes side effects is valuable, so the suggestions 
are provided as a starting point for the reader who may wish to develop his own 
style of good programming practice. 



You will also notice that some comments appear to be critical of the program 
style or of interfaces to the Multics supervisor. These comments should be 
taken in a spirit of illumination of the mechanisms involved. Often they refer 
to points which could easily be repaired, but which have not been in order to 
provide a more interesting illustration. Most of the points criticized are 
minor in impact. 
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The program listing appears after the commentary. 



Line number 

fifth unnumbered line 

The command "pl1 eds -map -optimize" was typed at the terminal. This 
line records the fact that the map and optimize options were used. 
The map line option caused a listing and variable storage map to be 
produced. A source segment named eds.pH was used as input; the compiler 
constructed output segments named eds. list (containing the listing) 
and eds (containing the compiled binary program.) 

1 No explicit arguments are declared here, even though eds should be 

called with one argument. Instead, the keyword "options (variable)" 
appears, which indicates that this program can be called with a variable 
number of arguments* This is a Multics extension to ANSI PL/I, Since 
eds is used as a command, it is a good human engineering practice to 
check explicitly for missing arguments; the PL/I language has no feature 
to accomplish this check gracefully. Library subroutines are available 
to determine the number and type of arguments supplied (see lines 
102-121). All Multics commands are declared and process their arguments 
in this way. 

3,4,5 It is common practice to include a short comment at the beginning of 

every program which briefly describes it. This should be followed by 
a comment or series of comments identifying the date of writing and 
original author, and the date, author and purpose of any subsequent 
modifications. This history, or "journalization" as it is called, is 
very helpful to others who may wish to modify the program in the 
future. 

9 To avoid errors when program maintenance is performed by someone other 

than the original coder, all variables are explicitly declared. This 
practice not only avoids surprises, but also gives an opportunity for 
a comment to indicate how each variable is used. 

9 One default which is used here (and is subject to some debate) is that 

the precision of fixed binary integers is not specified, leading to 
use of fixed binary(17). This practice has grown up in an attempt to 
allow the compiler to choose a hardware-supported precision, and in 
fear that an exact precision specification might cause generated code 
to check and enforce the specified precision at (presumably) great 
cost. In fact, the PL/I language does not require such checks by 
default (although they can be specified). Thus, it is usually wise to 
specify data precision exactly. In some cases (for instance, all of 
the fixed binary (21) variables used to hold string lengths), the 
compiler might attempt to hold these values in half-length registers 
were this precision not specified. 

However, a large class of variables which will contain "small or reasonable 
size integers" can still be conveniently declared with the 
implementation's default precision. 

12 All character strings in this program are declared unaligned, by the 

defaults of the language. Given the fact that the Multics hardware 
has extremely powerful and general string manipulation instructions, 
no advantage is to be gained in speed or length of object code by 
declaring strings (when they are over two words, or eight characters, 
long) with the aligned attribute. 

Therefore, almost all supervisor and library subroutines which accept 
character string arguments require unaligned strings. By the rules of 
PL/I, aligned and unaligned strings may not be interchanged as parameters, 
and thus, there is incentive to avoid aligned character strings in all 
cases. 
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All line buffers are designed to hold one long typed line (132 characters 
for input terminals with the widest lines), plus a moderate number of 
backspace/overstrike characters. To support memorandum typing, the 
buffers permit a 70-character line which is completely underlined. 

By use of temporary segments as work areas (see line 149), an almost 
unlimited number of nearly infinite work-variables can be constructed, 
virtually avoiding the "fixed length buffer" problem. However, the 
acquisition and maintenance of such segments are not as cheap as PL/I 
automatic variables, and judgement should be exercised as to where 
traditional "fixed length" variables are appropriate. 

14 The variable named "code" has precision 35 bits, since it is used as 
an output argument for several supervisor entries which return a fixed 
binary(35) value. Almost all supervisor and library subroutine entries 
return an "error code" value, which indicates the degree of success of 
the operation requested. The values of system error codes require 35 
bits. It would seem appropriate, on a 36-bit machine, to use fixed 
binary(35) declarations everywhere. However, use of fixed binary(35) 
variables for routine arithmetic should be avoided since, for example, 
addition of two such variables results in a fixed binary(36) result, 
forcing the compiler to generate code for double precision operations 
from that point on. We must be careful of the PL/I language rule 
which requires the compiler to maintain full implicit precision on 
intermediate results. 

15 Legal PL/I overlay defining can be an extremely powerful tool for 
increasing the readability and maintainability of code. . The variable 
"commands" is declared here as occupying the same storage as the variable 
"buffer", but only being as long as that part of it which contains 
valid characters, as defined by the value of "count". Thus, we need 
only write "commands" when we want the portion of "buffer" that has 
valid data in it, instead of "the substring of 'buffer 1 starting at 
the first character for 'count 1 characters." 

23,24 All editing is done by direct reference to virtual memory locations. 

The variable "from_ptr" is set to point to a source of text, and the 
based variable "from_seg" is used for all reference to that text. The 
number 1048576 (two to the twentieth power) is the largest possible 
number of characters in a segment. 

24,50 The general operation of the editor is to copy the text from one 
storage area to another, editing on the way. The names "from_seg" and 
"to_seg" are used for the two storage areas. 

43 One set of supervisor interfaces calls for 24 bit integers; this 

declaration guarantees that no precision conversion is necessary when 
calling these interfaces. (See line 133- ) 

56 The PL/I language provides no direct way to express literal control 

characters. The technique used here, while it clutters the program 
listing, at least works. The string is typed as a quote, a newline, a 
tab, a space, and a quote. This order is used because it produces the 
least ambiguous printed representation; for instance, had the tab and 
space been reversed, it would not be possible to distinguish by observation 
between the space, tab sequence and a single tab. 

PL/I does not provide any "named constant" facility, either. The Multics 
PL/I implementation allows the "options (constant)" attribute for internal 
static variables, which instructs the compiler to allocate the variable 
in the pure (unmodif iable) portion of the object segment. This is 
advantageous for three reasons: first, if an attempt is made to modify 
such a variable, the hardware will detect an error, thus checking and 
enforcing its "constant" use; second, it allows the variable to be 
shared between processes, conserving storage; third, it is an indication 
to others reading the program that a "named constant" is intended. 
These "constants" are customarily given all uppercase names, as an 
additional hint to the reader of their constant nature; this is a 
standard Multics PL/I convention. 
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64,77 Subroutines com__err__ and ioa__ are called with a different number of 

arguments each time, a feature not normally permitted in PL/I. The 
Multics implementation, however, has a feature to permit such calls. 
The "options" clause warns the compiler that the feature is used for 
this external subroutine. 

65 All subroutines other than com_err_ and ioa_ are completely declared 

in order to guarantee that the compiler can check that arguments being 
passed agree in attribute with those expected by the subroutine. Warning 
diagnostics are printed if the compiler finds argument conversions 
necessary. (All of the subroutines used by this program are described 
in the MPM Subroutines Manual. 

65 The procedure cu__ (short for command utility) has many different entry 

points. The Multics PL/I compiler specially handles names of external 
objects which contain the dollar sign character. The dollar sign is 
taken to be a separator between a segment name and an entry point name 
in the compiled external linkage. Thus, this line declares the entry 
point name arg_ptr in the segment named cu__. 

67 For many procedures, the segment name and entry point name are identical, 

so the compiler also permits the briefer form cv_dec_, which is handled 
identically to cv_dec_$cv_dec_. 

70 The hardcore (ring zero ) supervisor entries ( hardcore gates ) are all 

easily identifiable since they are entered through a single interface 
segment named hcs__. Segment hcs_ consists of just a set of transfers 
to the subroutine wanted. A transfer vector is used to isolate, in 
one easily available location, all gates into the Multics supervisor. 
(There are in fact hardcore gate segments other than hcs_, but you 
will probably not have occasion to deal with them.) For a discussion 
of the ring structure and hardcore gates, see the MPM Reference Guide. 

90 The program will need to know what I/O switches will be used in order 

to perform certain I/O operations. I/O switches are the general 
source/sink I/O facility of Multics. Multics PL/I programs manipulate 
I/O switches as PL/I pointer values. The two external variables declared 
on this line contain the pointer values identifying the standard terminal 
input and terminal output switches. 

92 As mentioned above, system error codes are returned by most supervisor 

and library subroutine entries. In one case, we will need to know if 
a specific error (see line 142) was returned by a supervisor entry. A 
segment ( error_table_) exists which has entry point definitions for 
external static variables (see Appendix A) containing all the possible 
values that can be returned as errors by system routines. The variable 
error__table_$noentry contains the value returned as an error code by 
system routines to indicate that "the entry you specified in the directory 
you specified does not exist". 

102 The first order of business is to determine how many arguments were 
supplied to the command, and also to find out whether the command was 
called properly. This is done by calling a library subroutine. 

103 If the error code from cu_$arg_count is nonzero, it means that the 
program which called cu_$arg_count was not invoked as a command. This 
usually indicates attempted use as an active function, which is invalid 
for eds. 
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104 The library subroutine com_err_ is called to print out the error message 
describing the invalid call. It produces an English explanation 
associated with the error code, which is obtained from a system-wide 
table (the error__table_) . It also causes terminal output to be produced 
even if the user is temporarily diverting output to a file. In general, 
com__err__ should be called to report all command usage and operation 
errors. The output from such a call looks like this: 

eds: This command cannot be invoked as an active function. 

105 A Multics command exits simply by returning to its caller. (See also 
line 437) • It should, however, clean up allocated storage, terminate 
segments, and return temporary segments if it needs to. In general, a 
program should do exactly the same things when it exits normally as 
its cleanup handler does. These actions are omitted for this return 
(and the next) because the program has yet to do anything which would 
require cleaning up, and because the variables which would inform the 
cleanup handler of its job have not yet been set. (See lines 133-134.) 

109 The eds editor must be invoked with exactly one argument. If it is 

not, we wish to print a message describing what was wrong, and suggesting 
the proper usage. This message is produced by picking an appropriate 
standard error__table__ code to describe the error, and assigning it to 
code. All the standard error_table__ codes are listed in the MPM Reference 
Guide, Section 7. 

113- The com_err_ subroutine, as well as the ioa__ subroutine (see line 

162), allows substitution of parameters in its message. The "*a" string 
here is used to get the command name into the error message. It is 
done this way, rather than simply putting "eds" in the message, to 
make it possible to change the name of the program by changing only 
the declaration of MYNAME. 

117 After verifying that the right number of arguments (one) was supplied, 

we access the argument. As pointed out above, this is done via library 
subroutine rather than PL/I parameter passing. Since the command argument 
is nominally unlimited in length, cu_$arg_ptr returns a pointer to the 
argument as stored by the command processor, and its length. The 
based variable "sname" will describe the argument once this pointer 
and length are obtained. The last argument is a zero, passed by value, 
because it is known that there is exactly one argument, and there is 
therefore no reason to receive or check the error code. This should 
only be done when it is guaranteed that no error can arise from the 
call, since it will otherwise result in faults. 

125 We must now convert the argument to a standard (directory name, entry 

name) pair. The subroutine expand_pathname__ implements the system-wide 
standard practice of interpreting the typed argument as either a pathname 
relative to the current working directory, or an absolute pathname 
from the root, as appropriate. 

134 The program will soon acquire (on line 149) a process resource, namely 

two temporary segments from the process's pool of temporary segments. 
When the program is finished executing, it will return them (line 589) 
to the pool. However, the program may be interrupted (perhaps by a 
QUIT, or a record quota overflow), and the user may abandon its stack 
frame (perhaps via the "release" command). In this case, it would 
seem that the program would not get a chance to return its "borrowed" 
resources. However, Multics defines the "cleanup" condition, which is 
signalled in all procedures when their stack frame is about to be 
irrevocably abandoned. (Refer back to Figures 5-1 and 5-2.) The handler 
for the cleanup condition invokes the procedure "cleanup", which 
relinquishes these resources. 
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The array "temp_segs" is initialized to null pointer values before 
establishing the cleanup handler, so that the content of the array is 
well defined at all times. (The release_temp__segments_ subroutine checks 
for null pointer values, and performs no action if it encounters them.) 
Otherwise, if the cleanup handler were invoked before the temporary 
segments were acquired, the pointer array would have undefined, probably 
invalid values, and the call to release the temporary segments would 
have unpredictable results. 

The cleanup handler is established before the temporary segments are 
reserved. This sequence guarantees that there will be no "window" in 
which the program can be abandoned between the time that the segments 
are acquired and the time that the cleanup handler is set up. 

139 The supervisor entry point hcs_$initiate_count is invoked to map the 

segment specified by the (directory name, entry name) pair into the 
process J s virtual memory. It returns a pointer to the segment, which 
it constructs from the segment number by which the segment was mapped 
into the virtual memory of the process (made known). If the segment 
was already "known", i.e., in the process ! s address space, the segment 
number from the existing mapping will be used to create a pointer to 
return. Refer to the MPM Reference Guide, Section 4, for details. 

The PL /I null string ( "" ) is a special signal that no (possibly additional) 
reference name is to be initiated for the segment. 

141 Unfortunately, the zero/nonzero value of the return code from 
hcs_$initiate_count cannot be used to check whether the initiation 
(mapping into the address space) succeeded. In the particular case of 
this subroutine and hcs_$init iate , a nonzero error code is returned in 
the ostensibly successful case of the segment having already been in 
the address space or the process, a case which is rarely an error. 

These two subroutines are defined to return a nonnull pointer value if 
and only if the segment has been successfully mapped into the address 
space, whether by prior act or anew. Thus, testing the return pointer 
for the PL/I null pointer value is the appropriate test for success. 

142 The editor (eds) will create a new segment (see line 496) if an attempt 
is made to edit a segment which does not exist. By comparing the 
value of the error code returned from hcs_$initiate count with the 
system error code stored in the variable error_table_fhoentry , we can 
differentiate the case of failure to initiate simply because the segment 
did not exist from all other cases (e.g., incorrect access to the 
segment specified) . 

143 The pathname__ subroutine is used here to return a string, which is 
then substituted into the message produced by com__err__, which is the 
representation of the pathname. This cannot be done by simply 
concatenating the dir_name, a ">", and the entry_name, since if the 
dir_name were ">" (the root directory), this would result in a f n invalid 
pathname containing the sequence ">>". 

149 A pool of segments in a process directory is maintained by the 

get_temp_segments_ and release__temp_segments_ subroutines. These 
segments are doled out to commands and subsystems which request them 
(via get_temp_segments_) and it is expected that they will be returned 
to the pool when there is no further use for them. This facility 
avoids the need for user programs to create and delete (or attempt to 
manage or share) segments needed on a "scratch" or "temporary" basis 
(for work areas, buffers, etc). Segments obtained from this facility 
are guaranteed to contain all zeros (truncated) when obtained. 
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The number of segments to be obtained is determined by get__temp_segments_ 
from the extent of the pointer array parameter. The name of the subsystem 
is passed to get_temp_segments_ both to facilitate additional cheeking 
by release_temp_segments, and to support the list__temp__segments command, 
which describes which subsystems in a process are using temporary segments. 

If the segment specified on the command line does not exist, the editor 
is to assume that it is creating a new segment, and go into input 
mode. The value of the variable "source__ptr" will be null if this is 
the case. 

The ioa__ subroutine is a handy library output package. It provides a 
format facility similar to PL/I and FORTRAN "format" statements, and 
it automatically writes onto the I/O stream named user_output, which 
is normally attached to the interactive user's terminal. When used as 
shown, it appends a newline character to the end of the string given. 
Programmers who are more concerned about speed and convenience than 
about compatibility with other operating systems use ioa_ in preference 
to PL/I "put" statements, because ioa_ is cheaper, easier to use, and 
far more powerful. 

The formatting facilities of ioa__ are used in a simple way in this 
example. The circumflex (""") in the format string indicates where a 
converted variable is to be inserted; the character following the 
circumflex indicates the form (in this case, a character string) to 
which the variable should be converted. The first argument is the 
format string, remaining arguments are variables to be converted and 
inserted in the output line. 

The storage system provides for every segment a variable named the 
"bit count". For a text segment, by convention, the bit count contains 
the number of information bits currently stored in the segment. The 
bit count of the segment being edited was returned by hcs__$initiate__eount 
(hence its name) on line 139- 

This statement converts the bit count to a character count. Note that 
we have here embedded knowledge of the number of hardware bits per 
character in this program. 

The PL/I language specifies that the result of a divide operation 
using the division sign is to be a scaled fixed point number. To get 
integer division, the divide builtin function is used instead. Note 
that the precision of the quotient is specified to match its size. 

Here, we invoke some of the most powerful features of the Multics 
virtual memory. This simple assignment statement copies the entire 
source segment to be edited into the temporary buffer named "from_jseg". 
A single hardware string-copy instruction is generated for this code, 
copying data at processor speed. The string-copy instruction may be 
interrupted by page faults on either "source__seg" or "from__seg" several 
times; after allocating or reading the required page, the instruction 
is restarted where it left off. Note that we are regarding the entire 
text segment as a simple character string of length "size". We may 
regard it this way because the storage representation for permanent 
text segments is, by convention, identical to that of a PL/I nonvarying 
character string. 

Be sure to read the comments embedded in the program, too. 
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175 The standard I/O system is being invoked to read a line from the 

user's terminal. The line is read from the I/O switch identified by 
the external pointer iox__$user_input . Although passing the buffer to 
be used as a character string would be more convenient, this set of 
interfaces was designed with maximal efficiency in mind, and this form 
of call is more efficient. Note that it would also be safer than 
passing a pointer to the character string, since that would allow PL/I 
to check that an appropriate character string was being passed, as 
opposed to a pointer, which can point to any data type. This design 
demonstrates the frequent tradeoff between efficiency and convenience. 

175 Subroutine iox_$get_line is often used for input rather than the PL/I 
statement "read file (sysin) into again because of efficiency 
and error-handling considerations. The PL/I facility ultimately calls 
on the Multics iox_ package anyway. (Again, if you wished to write a 
program which would also work on other PL/I systems, you would be 
better advised to use the PL/I I/O statements instead.) 

176 It is highly unlikely that a call to read a line from the terminal 
will fail. Nevertheless, in cases of people debugging their own extensions 
to the Multics I/O system (a practice intended by the designers of the 
I/O system), it can occur. It is reasonable to abort the entire editor 
in this unlikely case rather than repeating the call: presumably that 
would repeat the error too. 

180 For the sake of human engineering, the editor ignores blank command 

lines. Since complete input lines from the typewriter end with a new 
line character, the length of a blank line is one, not zero. 

182 The code to isolate a string of characters on the typed input line is 

needed in four places, so an internal subroutine is used. This subroutine 
is not recursive, which makes it possible for the compiler to construct 
a one-instruction calling sequence to the internal procedure. Certain 
constructs (e.g., variables of adjustable size declared within the 
subroutine) will force a more complex calling sequence. For details, 
you should review the documentation on the Multics PL/I implementation, 
contained in the Multics Pl/I Language Specification , Order No. AG94. 

1 84 Although the dispatching technique used here appears costly, it is 

really compiled into very quick and effective code — 2 machine 
instructions for each line of PL/I. For such a short dispatching 
table, there is really no point in developing anything more elaborate. 
If the table were larger, one might use subscripted label constants 
for greater dispatching speed. 

189 Human engineering: the typist is forced to type out the full name of 

the one "powerful" editing request which, if typed by mistake, could 
cause overwriting of the original segment before that overwriting was 
intended. 

200 Whenever a message is typed which the typist is probably not expecting, 

it is good practice to discard any type-ahead, so that he may examine 
the error message, and redo the typed lines in the light of tnis new 
information. 

207 The general strategy of the editor is as follows: lines from the 

typewriter go into the variable named "buffer" (accessed as "commands") 
until they can be examined. Another buffer, named "line__buf fer" (accessed 
as "line") holds the current line being "pointed at" by the eds conceptual 
pointer. Subroutine "put" copies the current line onto the end of 
to__seg, while subroutine "get" copies the next line in from_seg into 
the current line buffer. 

225 The procedure get_num sets up the variable "n" to contain the value of 

the next typed integer on the request line. Such side-effect communication 
is not an especially good programming practice. 
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226 The delete request is accomplished by reading lines from from_seg, but 

failing to copy them into to_seg. If deletion were a common operation, 
it might be worthwhile to use more complex code to directly push ahead 
the pointer in from_seg, and thus avoid a wasted copy operation. 

237 More side-effect communication: the variable "edct" is always pointing 

at the last character so far examined in the typed request line. 

254,265 All movement of parts of the material being edited is accomplished by 
a simple string substitution, using appropriate indexes. 

284 The locate request is accomplished by use of the index builtin function, 

used on whatever is still unedited in from_seg. 

422 A negative number in the next request results in moving the conceptual 

pointer backward. The resulting code is quite complex because the eds 
editing strategy requires interchanging the input and output segments 
before backward scanning, so that the backward scan is with regard to 
the latest edited version of the segment. 

427 This code to search a character string backward is recognized by the 

compiler as such. Extremely efficient object code to search the substring 
backward is generated, using a single hardware instruction. No copies 
are made in this fairly expensive-looking statement: it is, in fact, 
cheap. Combinations of reverse, index, substr, search, verify, etc. 
that seem like they ought to generate efficient code in fast usually 
do. The -profile control argument and the profile command are useful 
tools for discovering where inefficient code is causing performance 
problems . 

456 Before exiting from the editor, the temporary segments should be returned 

to the temporary segment manager, and the segment that was initiated 
terminated. 

468 Another human engineering point: since the user may have typed several 
lines ahead, the error message includes the offending request, so that 
he can tell which one ran into trouble and where to start retyping. 

469 Note a small "window" in this sequence of code. If the editor is 
delayed (by "time-sharing") between lines 468 and 469, it is possible 
that the message on line 468 will be completed, and the user will have 
responded by typing one or more revised input lines, all before line 
469 discards all pending input. Although in principle fixable by a 
reset option on the write call, Multics currently provides no way to 
cover this timing window. Fortunately, the window is small enough 
that most interactive users will go literally for years without 
encountering an example of a timing failure on input read reset. 

500 Note the practice of copying data into the original segment, setting 

its bit count, and truncating it in that order. This provides for 
maximal data being saved should there be a system failure between any 
two lines. Common sense seems to indicate this order as "maximally 
safe", and analysis of the data involved will demonstrate this as 
well . 

538-540 The input and output editing buffer areas are interchanged by these 
three statements. Here is an example of localizing the use of pointer 
variables to make clear that they are being used as escapes to allow 
interchange of the meaning of PL/I identifiers. 

551 The I/O system provides this entry point to perform control operations 

(e.g., "resetread") upon the objects represented by I/O switches. 
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563 This editor considers typed-in tab characters to be just as suitable 

for token delimiters as are blanks. Ideally, tab characters would 
never reach the editor, having been replaced by blanks by the typewriter 
input routines. Such complete canoniealization of the input stream 
would result in some greater simplicity, but would require a more 
sophisticated strategy to handle editing of text typed in columns. 

563, 566 The PL/I search and verify builtins, which are quite useful in 
circumstances like this (parsing lines), are compiled into very efficient 
single-instruction hardware operations by the Multics PL/I compiler. 

580 The cv_dec_ library routine is used here rather than a PL/I language 

feature, because cv_dec_ will always return a value, even if the number 
to be converted is ill-formed (in which case it returns zero). Thus, 
the editor chooses not to handle ill-formed numbers. Had it wished to 
check for them, it could have used the cv__dec_check_ subroutine. PL/I 
language conversion would cause an error signal which must be caught 
and interpreted lest PL/I T s runtime diagnostic appear on the user's 
console. Thus, eds retains complete control over the error comments 
and messages which will be presented to the user. Such control is 
essential if one is to construct a well-engineered interface which 
uses consistent and relevant error messages. 

589 The cleanup procedure calls the release_temp_segments_ subroutine to 
release the temporary segments acquired earlier. A binary zero is 
passed to release__temp_segments_ by value (by enclosing it in parentheses) 
because the cleanup handler has no use for an error code. Cleanup 
procedures should never print messages, even error messages, because 
they are only invoked when exiting a procedure. There is no corrective 
action the user can take. 

590 If the segment edited was not known before editing it, it should be 
unknown after the editor finishes as well. The supervisor maintains a 
reference count for each segment in the process. This count is incremented 
by the call to hcs__$init iate and decremented by the call to 
hcs__$terminate_noname. If the count goes to zero (i.e. the segment 
was made known by the editor), then the segment is made unknown. 
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1 a re 


c^unt 
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/* Valid length of data in "buffer " 




1 R 


dec 


i a P« 
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e^c* 




*ixeH binary; 
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/* Temporary Pointer bolder. */ 
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| A P n 
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n 
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! are 






cnaracter Csna^e^l^h) ^ased ( sna^e.pt r ) ; /* Source name */ 






dec 


1 a Pe 
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fi*aH binary 


/* Length of source segment name. */ 
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] a re 






r»ointe r ; 
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1 a pe 
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He- 


[are 


SOu"Ce_r<tP 




pointer; 


/* Pointer to source seg. */ 




as 


dec 


1 are 






character Ci^4«t>7d) ^ased (sogrcej^tr) J 
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*/ 
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Her 
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HiTersicn C/ii) pointer; 






aft 


Her 


1 arc 






character f ^ 10 ) ; 


/* Buffer to hold outout of cbange. 


*/ 




Hec 


1 a r*> 






character O:"!; 


/* Holds, next item on typed line */ 
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Hec 
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55 
56 
57 
58 
59 
60 
61 
62 
63 
64 
65 
66 
67 
68 
69 
70 
71 
72 
77 
74 
7? 
76 
77 
78 
79 
80 
81 
82 
8? 
84 
85 
86 
87 
88 
89 
90 
91 
9? 
93 
94 



dec! are 
*)? 

decl ere 
dec 1 are 
/* 

dec 1 ere 
decl are 
dec 1 are 
dec 1 are 
decl are 
dec 1 ere 
decl are 



dec 1 ere 
dec 1 are 
dec 1 are 
^ec 1 are 
decl ere 
decl are 
declare 
decl are 
decl are 

decl are 
dec 1 are 



character (l) static ootions (constant) initial f" 
character C3) static options (constant) initial (■ 



NL 

*HIT£$PACF 

/* M L TA© SPACE */ 

MYNAI-iE character C3) static ootions (constant) initial ("eds"); 

external subroutine dec 1 aret i ons . */ 



cu_*arg,_count 
cu_^arg_pt r 
cv_dec_ 

get_temo_seoment s_ 
hcs_Si ni t iate^cnunt 



declare hcs^^^ake_seg 



hcs.Sset^bc^ sag 
hcs..$termi nate.no^afe 
h cs_.it runcate^seg 
ioa_ 

i ox_$cont rol 
i ox_$aet_1 i ne 
icx_$Put_chars 
pat Hname_ 

rel ease_temo_seoment s. 



ent rv 
ent rv 
ent rv 
ent rv 
ent rv 
*nt rv 
ent rv 
fixed 
ent ry 
f i xed 
ent rv 
ent rv 
ent rv 
ent rv 
ent rv 
ent rv 
??nt rv 
ent rv 
ent rv 



options (variable)" 

(fixed binarv, fixed binary (35)); 

(fixed binary/ Dointer* fixed binary (21), fixed binary (35)); 
(character (*)) returns (fixed binarv(35))? 

(c^arpcter (*), character (*), character (*), fixed binary (35)); 

(character ( + ), oointer dimension (*), fixed binary (35)); 

(character (*), character (*), character (*), fixed binary (24), 

binary, pointer, fixed binary (35)); 

(character (*)# character (*), character (*), 

bin (5), ptr, fixed binary (35) )? 

(pointer, fixed binary (24), fixed binarv(35))? 

(oointer* fixed binary (35))? 

(pointer, fixed binary (19), fixed binarv(35)); 
ootinns (variable)? 

(pointer, character (*), pointer, fixed binary (35))? 

(pointer* pointer, fixed binary (21), fixed binary (21), fixed binary (35)) 

r«.i.t«». * 1 ~ - - L. J _ », 00 4«vs"4 U ^ C 7C ^ \ • 

v Q f - ■ i. C I » uOllllB' f I 'SBU W I tlO| r v (. A i r t | A c u M t ■ 1 Q > T \ J J t f » 

(character (*), cnaracter (*)) returns (character (168))? 
(character (*), oointer dimension (*), fixed binary (35))? 



cleanup condition? 

(addr, divide, index, lenot*, null, reverse, search, substr, verify) 
*ui 1 1 i n; 



/* Fxternel data */ 

declare ( i ox w $user_outout , i ox_$user_i *put ) 

declare er ror_t abl e_Sno*ro 

declare er ror_t abl e_$noent rv 

dec 1 are er ror_t abl e_St oo_f"any_a rgs 



oointer external static; 

fixed binary (35) external static; 

fixed binary (35) external static; 

fixed binary (35) external static; 
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95 
96 

97 /* . . . P P H R P * M . # . */ 

9P 
90 

10 ft /* C u ec* tn pep if a^ inou* arfu«e"t *as given */ 
t 01 

10? call cu_'fjr^count (ara..countf coop}; 

10^ if coa» *= 0 t^en /* Mot calleH as a commend */ 

104 call co^.em. (ccHe* ™\ ?, A« B *E ) ; 

1 0*> return; 

10* fnri 
1 07 

103 if a^g^count s i t^en co H e = 0? /* This Is correct */ 

1 \) q pise if aro.ccunt = then coae = er^op.taMeJnoargf /* Arroument is missing */ 

11° else coop s error.t&^ie.Stoo^^ny^arrs! /* Otherwise* there were too manv */ 

1 11 

. M? if coci« *s 0 t^e* r?of /* If not called correctly, complain */ 

117 call co^pp. CcoHer ^ t r "*/Usa-)e; A - A a <PATH>", MYNAMF)? 

1 \a return; 
J IF en*; 

116 

117 ca 1 I cu_Sar9_.pt r C J. * sra^e^otrf sna-r f e_lth, (0)); 

11- B - if ends A = 0 t^en h c ; 

11° ca]l co^rr, (code* "v'-^'t, "usaoes *a <PATH>% HYNA^E.) ; 

1 2 $ return; 

121 

12? /* i-'o* o p t a oointer tn tn° Segment to dp edited */ 

!2.a 

12* ca 1 ! exp^n^nef hna^e.. fsna^e* riir^na^e, entrv^name* code)? 

126 if code * = 0 then do J /* Bad pathname */ 

127 cap ro^„ppp. (co^er * A i WE , " A a", snarce)* 
return; 

12° <*nC; 
1 30 

lil /* ^et- up a cleanup hen^l^r in case the orooram is aborted */ 
13? 

- 13^ source_u.tr = null f): 

13« te*r-p_sec« f*i " null Ui /* Make sure handler has valid data */ 

13* on condition (clear-uo) cajl clean_up; 
136 

137 /* Initiate the source sei^e^t. */ 
138 

13° ca 1 1 ncs.* i ni t i ate_count (Hi r^naf© r entrv.name^ w % souree.count * 0/ source_t»tr/ code) J 

/* Initiate the segment */ 

141 if SOOrcP^f" = n^l ) O 

t^e n if ccae *s errop.t at>l e_Snoent ry then do;/* Problem or Just new aeg? */ 

14"* caU cn^_err_ Ccode* i-,VNft.v ( ^ # "Cannot access *a% oathname_ (dir_name* ent rv.name) ) $ 

IV* return: 

l£ c end; 
1 U6 

t^7 /* 5 et us suffer segments. */ 
14A 

rail .^et_tenri w «e^rf:pnt s_ C-iVj,A&*F r ter-r^secSf code); 

15° if code *= o t^en do? 

151 call co^_er'-_ (ro H e» M Y»"A?'£> "Cannot oet temporary segments. ■) t 

1b? call clpan^uor 

1S T return; 

!5« en- 1 ; 
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t 5^ 




1 s a 




1 




1 t^g 


/* 


j SO 








1 A i 




1 6? 




1 




1 t>^ 












1 67 




1 of 




1 o* 5 


/ * 


17^ 




1 7 i 




17? 








1 7/! 




1 7^ 




1 7 




177 




17* 




17° 




i<Sf. 




til 




i«? 




16"? 




J A /I 




i 6 C 




: a** 




1 67 




IS* 




1<jC 




1 




1 *1 




vt? 




I 9 7 




1 G£ 




t9S 




19* 




1 97 


/+ 


t<3«. 




1 ?f 




?un 




?C1 




?0? 








?oa 




?u c 


r i r; 







/* Initialize buffer control vers. */ 



* rtxr.^vt r = tenir^secs ( 1 J * 
*o_ptr = t^mo^cseos C 5 )! 

/* Oecfc t o «ee that the seg«re^t i «? there */ 

rsiz^f i "O-f r i ->ot = ^ ; 
if sou*ce_ r! t r ~ null then Ho? 

call io» w ("Segment *e not ent "y.nawe) I 

go t& oinr>ut; 

rsize - Hivi^e («source„coont^ S c"1» 0); /* change bit count to char count */ 

sj'-str (fropi„8^» % c?i?e) = su^sfr (source_segr \, csize); 

/* Move source segment into buffer. */ 



r ain e^i t i ng loo? 



cit." 



--a 1 i 1 ox.Soet.l i o e (i'oy.*user_inruN adar ftiuffer), length (buffer)r countr code)? 

if cod** *s 0 then ^c? 

ca]i co", n ri*. (cc*e» f -">'* M fc» "t^or reading input line"!)? 
30 to finis*-. 



*■ n^ ; 



5 f 


count 


s i t^eo 


00 


to 


n e x t ? 


e jr 


t = 


1 * 










ea • 


1 u« 


t_ 


,tnk.en: 








i f 






"i" t'-er- 


"0 


to 


i nse r 1 1 


i t 


t^n 






00 


t n 


retype' 


i f 


tfn 




» 1 " t k e « 


"•0 


to 


locate? 


i f 


t if n 




"n" t^er 


0:0 


to 


0 r i n t ; 


i f 


t *n 




" n " t ^ e n 


no 


t 0 


0 e x 1 in? 


* f 


t 




"save" t h p n 


*o 


to file; 


i f 


t*n 




"c" tien 


no 


to 


r n s»noe * 


i f 


t in 




■M" t^en 


OG 


to 


del i i n' 


i f 


t*n 




" w " t i* e r 


°o 


t 0 


ws«ve; 


i f 


t «rn 




" t " t •* ft « 


"0 


to 


t or? ; 


if 


t <n 




"K« t Hen 


no 


to 


Cotton? 


< f 


tVn 




" . " t * e r 


CO 


to 


ri nput ? 


nii» n 


f t k 


e 


3 x o«€ t k en f- 


ot 


a request */ 


c a 1 1 i fta. 




•.ot 


ao 


pjit Wequest"» 



/* if null line then get another line, don't orint error */ 
/* Set up counter to scan this line. */ 
/* Identify next token. ★/ 



?Q7 



esi 1 reset r e ac»: 
7>o t rt nert: 



*+ a ****** ioyut rtooe ********* */ 



/* print word input */ 



ca 1 1 iox.icie^.lire (I'oy.^user.innut, ado> (ouffer), length (buffer)f count* code)? 
i f COG«* *= U the" ^o? 

call co^»rr_ (cc^e, ^' r "A'-'t » "trror reading input-mode line.")? 

90 to finises 

en-i; 

if swbstr fcoin^ao c s f i, 1 ) = " . M i count = 2 
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?1? 

?17 
?20 

?£7 

?30 

231 

?3? 
?33 
?3* 
?35 
?36 
?37 
?3« 
?3° 
?an 

?4\ 

?'4'4 

?47 
?4* 

?51 
?5? 
?S3 
?b« 

?57 
?5* 
?5<5 
?60 
?o1 
?6? 
?0J 
?6A 
?b* 
?66 
?67 
?6* 
?6<* 
?7* 
?71 
?7? 
?7* 
?74 



thjjn t n n e i * # 

r 1 put ? 

Hnel r le^cth I r c" 1 nan-is ) ; 
<-o to in^ut, 



/ * ********* qp ] ********* * / 
r-eH i nr 

Co* I S D t„nU'^; 
«0 i - 1 ton- 1 ; 
c»H net; 

en- 1 ; 

line! - 0; 
oo to n e xt? 

/* ********* insert ********* +/ 
insert : 



r a H Put? 



Hnel = length Ccc^nands 1 - ecict? 

oo to n e vt? 
/ * ********* r, a / f ********* */ 

nev]in: call qet^nur, : 

if n < 0 t^en oo to hacKUO" 

«# j = incif; 

ca 1 1 put ? 

Ho i s 1 to r ; 

if j >= csize t K en to n_eof# 



/* check for mod* ehanqe */ 



/* movf line inputted into i ntermedi ate storage */ 
/* repeat 'til */ 



/* do for each line to be deleted */ 
/* nul 1 i f y 1 ast line */ 



/* Add current line to output segment */ 
/* This is also the retype request. */ 



/* add replaced line */ 



/* save where vou are */ 

/* once for each nl */ 
/* check for eof */ 



k - inti»x (substr CfrOT,^se<?f J + J, csize - j ) , NL) ; 

/* locate end of line */ 

i f w s o then co; /* no nl (eof) print eof */ 

if indf >= c?ize t h en oo to eof; 

lire! = /* set to no line */ 

substr (to,3sa? indt + \ f csiz* - rr.) s substr ffrom_seq# m + 1 #- csize - m) I 

/* move in top of file */ 



indf s csi?e? 

i n d t - i n c t + csize - m ; 

oo to ^cf/ 

en 0 ; 

j = j + <' 

end; 

indf = j? 
i in e i = k; 

line = subsf ("fro^seo, j - k t i , lineU? 



/* set pointers */ 

/* increment j bv length of line */ 

/* set pointers and move in too of file */ 

/* put working line in line */ 



substr (tc.se^, indt * I* indf - linel - m) = substr (from_seg# m + 1, indf - line! - m)t 

/* fil 1 rest of file */ 

i n H t - inct + indf - j i n e 1 - t- * 
oo to n e Yt J 



/* ********* locate ********* */ 

ica^e' if e H ct = length (Co" -aen-^s 1 then go to oad^svntax; 
•*.-;ot = edct * 1 ; 
! r indf 



/* check for olain "1 NL" */ 
/* Skip delimiter. */ 

/* initialize nointers for index type search */ 
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275 m - indf; 

276 r* r csize - indf? 

277 can put? 

278 if (csize = fi) I (n <= 0) then do; 

279 call switch? 

280 if i > 0 then n = j - 1? 
261 else n = 0; 

282 m, J = h f 

28? end; 

28a i s index (substr (f ron„?eif indf + If n)» suostr (commands, edct, length (commands) • 

285 if i *s 0 then do; /* if found then do */ 

286 < s index (reverse (suostr (fro?*_sear l, indf + i)), N|_)# 

287 if lr *s o then k = i n df + i - k + 1? /* k = index of WL */ 

26P j = index (substr (^ro^seq, k + 1, csize - k)r NU; /* find end of Hne */ 

280 if j r a ther ind ^ = cs i Z e; 

290 else indf s j + <; 

291 substr (to_se<V inat + 1, it - iO = su^str- (from_seg, m + 1, k - m); 

292 /* move in top of file */ 

293 linel = indf - k; 
29a indt = indt + k - m? 

295 line = substr (from_segr k + 1# linel); /* put found line in line */ 

296 n = i; 

297 go to PM'ntl; /* print found line if wanted */ 

298 end? 

299 cal 1 copv; 

300 call swi tch; 

301 no to next; /* get next command */ 
302 

303 /* ********* print ********* */ 
30" 

305 orints call get_nur. t ? 

306 if linel = 0 t^en do : /* print indication of no lines */ 

307 call ioa_ ("No l me."); 
30R go to nol ine; 

309 end? 
310 

311 orintl: call i ox_$out_ehars Mox.K'ser.outnuN add^ (line), length (line), code)? 

312 if code *= 0 then d 0 « 

313 call co*_err_ (code* r *fMA"*£, "Problem siting editor output"); 
3ia go to finish; 

315 *nd; 

316 /* *ri te the 1 i ne */ 

317 nol i ne ! n = n - 1 ; 

31* if n s 0 then co to next? /* any mora to be printed? */ 

31° call put; 

320 call get? 

321 ao to orintl? 
322 



323 /* ********* change ********* */ 
32a 

325 chenoe: located = 0; 



326 if count = 2 then do' 

327 bad_syntax5 

328 count = count - U /* Strip NM- off "commands * */ 

329 cell ioa_ ( "I^o rooe *a", cotf*ands)? 

330 cal 1 reset read? 

331 go to next; 

332 end; 

333 brkl = edct + 2; 

33a break = substr (commands* eact t I, ))i /* Pick up the delimiting character. 
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3S^ i = '"nHev Csubst" r c '"vp* anas, brkl)» Hpeatf) 5 

"556 if i = G then no tn ^ai.s^t^x? 

337 i = index (substr ( c o^*a rt ds / i + prkl), break)? 

33? if j =0 t^en ' ~ le^yth (co^manHs) - i - h r kl + 1? 

ea<*t = e^ct + i + I + i. ; /* Continue scanning edit line, */ 

3^0 oIodsw = /* Assume only one change. */ 

341 n = l; /* Assume only one Hne changed. */ 

3*? nxarn: 

3<n csl 1 get.tr k*>n; 

3afl if tkn ~ = " " then d<->; /* If token there, Process it. */ 

34* if tkn = "q M then qlobsw = "i"o? /* Chanqe all occurrences. */ 

3«6 e^se call cv.nu"/ 

3^7 go to r.varp: /* Try for another argument. */ 

jap pnr*? 

3^Q if line] = 0 tHen to ski ^ch ^ /* Skip changing empty line. */ 

35C 

351 chl: cnanae$_occu«T-<»a = ,,rsf, h; 

^S? m, iJ f 1 = i? /* indexes to stringa */ 

3b3 if i = i t^en -*o*, /* add to beginning of line */ 

35/-' ch a nyes.orcup re H s "i"o? 

35? locate^ = i? 

356 substr ftMn, 1, I - 1j = suDStr (commands, b^kl + ir j - 1)? 

7 57 /* copy oart to he added */ 

358 supstr r tli n r if lengtn Pin e )) = line; '* copy oH line */ 

359 i J = J + 1 i n e i - i ; 
36H 1 = j + fine] + it 
361 g<o to c n rt; 

3b? pnr 1 ; 

363 ch?; V ~ inH e x fsur^tr Mine* sO # suostr C c n-n^an ds , brklf i " l))f 

3©fl /* locate what is to be changed */ 

3^ c if k 0 then do? 

36A SMbstr (tHn, is, < - j. ) s sucstr dine, m, k - 1); 

3o7 /* copv line uo to change */ 

36* substr ft 1 in, i T + * - 1. , j - l) s sobstr (commends, b r kl + i , J - 1); 

3o9 /* put in change */ 

37^ At = m t ■ i - t ? /* increment inaexes */ 

371 i I - i j + k + j - c'r 

37? 1 c 1 + k + j - 

^73 c^anges^occ-'rre^ = *i"o9 /* indicate that you did someting */ 

?7« 1o c ateo = i: 

7 7 5 olObSw ^pr, to Cfl?f 

376 «n^/ 

3/7 sucstr (tlin, ij, le^oth Pine? - m * 1) = subst r (line, nOj 

37°> /* ceov rest of line */ 

379 ij = il + length Cli^a) - 

330 1 r 1 + l e^citr C 1 i re) - 
3 81 cor tz 

36? if cHa^ies.occur-e^ tr>en oo, /* ^*rite changes */ 

363 call ioxjDut.c^^ i. i ox_*user^output # ad^r (tlin)r If code); 

36^J cor 1 ? ^ then j^; 

38^ ca'l con w e r r„ Ccoje, * • r , "Fr^or wpitino change line"); 

3<i^ no to f i n i *?r : ? 

3 7 e n fj j 

38* 1 irel = i j ? 

390 Hne = sucsf r tlin r i, ij); 
391 

39? sxirchr i f n <= i then sin; /* finished */ 

"^93 i 4 locate^ s 0 tnen 

3v^ count = count - !; /* Get rid of ML i "commands" */ 
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395 call ioa_ (""otMnq changed by! A a% commands)? 

396 /* if not located */ 

397 call p^sefe^; 

398 end; 

399 90 to next; 

400 end; 

401 n = n - J; 
40? call put? 
a03 call g*t? 
aQ4 oo to chl; 
aos 

aQ6 
ao7 



ao* /* ********* top ********* */ 

009 

aiO too: call copv? 

ail call switch; 

41? qo to next? 

ai? 

aia /* ********* bottom ********* */ 
ai5 

ai6 bottom; call copv; 

ai7 linel = 0; /* Mo line buffer */ 

ai* no to oinput? 

419 „ 

a20 /* ********* backyo ********* */ 



a21 

a2? backup; * = indt? /* save Dtrs */ 

423 call copv; 

a2a call switch; 

425 indf = i + 1? /* restore otrs */ 

a26 do n = n to 0; /* N 0 te that "n" starts negative, 

a27 j = index Reverse fsubstr (fro-n^seo, I, indf - 1>), N|_); 

42* if J 0 then indf s ind* - I; 

42$ else if n = 0 t^n indf = C? /* First line cas« */ 

a30 else do? 

431 line! = 0? /* *#nt off too of file */ 

432 n = 1} 

433 inH t , in*f = 0? 

434 oo to eof; 

435 end; 

436 end; 

437 in^t = ind*; /* line starts as indt */ 
43* substr Cto.segr \, i"Ot) = substr (fro"_sec? 1 , indt); 

439 /* move in top of file */ 

440 do indf = inHt t 1 by 1 to csize? /* find end of line */ 

441 3ubstr Cline, ina* - Indt* I) = substr (frow_sea* indf, 1); 

fl 4? /* move into line */ 

a43 if substr ( *ron _segr indf, J) s \d. 

al * a then qo to Mne^eno! /* search for end of line */ 

fl45 end; 

a46 indf = csize? 

447 Hne.end: 

a4B linel = Indf - indt; 

449 n r l; 

450 oo to oHntl? 
451 

45? /* ********** "file" renuest ********** */ 
453 

45a file; call copy; /* Finish copv. +/ 
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eel i sftve; 



/* Save it. */ 

/* Terminate source and release temp segs */ 

/* Peturn ta command processor */ 



/ * + write save *********** * /" 

Hsav*>; ca 1 ! copvj 
ca! I save* 
no to n^xt" 



«*o f z 



/* Finish copv. */ 
/* Save it. */ 

/* Continue accepting requests. 



eof 



co"nt = count - <t /* Remove */ 

ca^l ioe_ ("FnH of Fi]e reached hy:*/*a"# commands); 
c c*T 1 reset reao* 
no to next' 



/* ********* I 



T t K A L 



c p. \\ p P <? 



Syhstr (to_seq* in^t + 1» ^npth (line)) = line? 



/* copy rest of file into to file */ 
/* Cooy current line. */ 
/* No more 1 ine V 



i n H t = i n o t + 1 e n c t h ( 1 i n e ) J 
1 i n e i - n ; 
if c s i 7 e - u 
t h » n return; 
i j = c ^ i z e - i * cs f r 
if i f > « 

*hen substr (to„sec^ injt + t, il) s sub«tr Cfrom w geo/ indf ♦ if 
indt = inct + ij? /* set counters */ 

in^f = csize? 
return? 



/* If new input* then no eoDy needed. */ 
/* do rest of file */ 



e"0 cepv? 

f rroceoi'r*; /* Proceoure to write out all or part of "jo" buffer. */ 

if sou?*ce_Ptr - null t^en dc? /* Must be a new segment */ 

eel 1 hcs.Sirake^eo Cdi cna^e, ent ry^raT.e* H % QIQtQb* source.otr, code)? 

if cede * = n then 

call c<v ?! _err_ ^cogp, v: ' # "Cannot create *a% pathname^ (dir.namer ent ry.name) ) J 

return; 

end? 

e n H f 

sunstr (%urce.s9p, !# inotj = suostr fto_sea, i, indt); 
call hcs_iset_rc_sec C source.pt r, in^t * 9> code); 
if code - 0 

fn*»n cap ^cR.'t roncat*>„-se^ f scarcest r, divide Cindt + 3* 19* 0)* code)? 
if cod* * = 0 the* do? 

call cc" ! „*»rr. (code* ' "Cannot truncate/set bit count Co) on A a*'# 

indt * oarr.na^e. ( o i r_ne^e # e^ t ry_name) ) * 

enr'; 
return? 



e n g s ft v * i 
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515 put; 

516 procedure? 

517 su^str (to_seg* indt t 1* lenoth (line)) = line; /* do move */ 

518 Indt = indt + length (H^e); /* set counters */ 

51° line! = 0? /* Discard old line. */ 

520 return? 

52J end? 

522 

523 

524 qet: 

525 procedure; 

526 line! a 0* /* Reset current line length, */ 

527 if indf >= csi?e the* no to ec** /* If no Incut left* give up. 

528 line! * index Csubstr ffro m _sea* indf + i, csize - ind*)* ML)* 

52° /* Find the next new line. */ 

530 if line! = 0 then line! = csize - indf; /* If no nl found* treat end of segment as one. 

531 line = subsf f f rom_seci* indf + 1* Hnel); /* Return the line to caller. */ 

53? indf = line! + ind*j /* M ove the "from" pointer ahead one line. */ 

533 return; 

534 end; 
535 

536 switch? 

537 orocedure* /* maice fron-file to file* and v. v. */ 
53* exotr = from.ptr; 

539 f rom.pt r = to.rtr; 

540 to_ptr = exptr? 

541 csize = indt? 

542 indt* indf = 0? 

543 Hnel = 0; 

544 return; 
545 

546 end switch; 
547 

548 resetreed: 

549 procedure; /* Cell i/o system reset read entry. */ 

550 /* In one place to centralize error handling */ 

551 call i ox.Scont rol ( i ox_*'»ser_i nput * " reset read" * null O* code); 

552 if code *s 0 t*en caM co^erp. (cooe* WYfoME, "Cannot resetread user.i nout " ) f 

553 return; 
554 

555 end resetread; 
556 

557 eet_token: 

558 procedure; 
559 

560 declare rtoken.lth* white.1t*) fixed oinarv (21); 
561 

562 tkn s n /* Set for easv failure */ 

563 whitOth = verify (syhstr (commands, edct)* flHITESPACO - It 

564 if white.lth < 0 then return? /* Only whitesoace left */ 

565 edct = edct + whiteJtS 

566 to^en.lth s search Csubstr (commands* edct)* 4HITESPACE) - it 

567 if token.lth < 0 then token. fth r length (commands^- edct; - 

568 tkn = substr Cco w mands# edct* token.lth): /* Extract token */ 

569 edct = edct + token.lth; 

570 return; 
571 

572 end get. token? 

573 

574 
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'7 K oet^r.yr; 

If- p'-oce^gre ? /* Pontine to convert token to binary integer. */ 

7 7 ea'l c4*t_toKf>n; /* Delimit the token. */ 

7 P ev „n u t. ; 

7<? entry: /* Enter here if token already available. */ 

5^ n r cv_d*»c_ ft^n^; /* Convert it. */ 

51 i f n = o the n n r 1 ; /* Default eount is 1. */ 

3 P »• e t u p n ? 

• 

6^ e^o g?t nu«** 
r 1 a n _up - 

8? 

9^ if source^* r *s njl ] t K en rail hcs.jterfninate.nona^e ( sou rce.ot r * CO))? 
91 

9? eno cle»n_uo; 
91 

9 & s^a eds? 
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SOURCE FTLFS USE* TN T"I« CU^PILUTjN. 

0 06/01/B1 76^3.1 eos.oH >udo>Pubs>use r d>AG90-0 2>eds , o U 
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NA*ES HECLARPD IN THIS CnHPILA.TION. 
IDENTIFIER OFFSET L^C STuPACc CLASS DATA TYPE 



NAMES DECLARFD 8Y DECLARE STATEMENT. 

MYNAME 0000^0 constant 



NL 

WHITESPACE 
addr 



arg_eount 
break 
brkl 
buffer 



*hanqes_dccurrec3 
»anup 
le 



com_er r_ 
commands 



count 



csize 



cu_$arcu.count 
Cu_Sarq,.pt r 
ev_dec_ 
di rename 

divide 
edct 

ent ry^name 

error„t abl e_$nearg 

error^tab] e_$neent ry 

error_tabl e_Stoo_meny_args 

expand_pathneme_ 

exotr 

f rom.pt r 



0Qfll0£: constant 
00^001 constant 



000100 automatic 

^OOlOi automatic 

nOOJOH automatic 

0001*3 automatic 



char(i) 
cHar(3) 

builtin function 



fixed binfl7,0) 
cHar(l) 

fixed binfl7,0) 
char(?l0) 



000170 automatic bUH) 
00^472 stack reference condition 
^0*171 automatic fixed binC35,0) 



ftQOGIO constant 
basea 

°00172 automatic 
000i73 automatic 



000012 constant 

000014 constant 

00^0J6 constant 

000175 automatic 



000174 automatic 

000247 automatic 

O0O0S6 external static 

000060 external static 

100062 external static 

000020 constant 

000260 automatic 

000262 automatic 



ent ry 
c^ar 

fixea Dinf21,0) 
fixed binf21,0) 



ent ry 
ent ry 
entry 
char(16P) 

builtin function 
fixed bin(i7,0) 

char(32) 

fixea bin(35,0) 
fixed bin(35,0) 
fixed b<nC35,0) 
ent ry 
DOi nter 
poi nter 



ATTRI8UTES AND REFERENCES 
f* indicates a set context) 



initial unaligned del 60 set ref 104* ill* 113* 119* 
119* 127* 143* 149* 151* 177* 210* 313* 385* 498* 
507* 552* 589* 

initial unaligned del 56 ref 219 286 288 427 443 528 

initial unaligned del 58 ref 563 566 

del 85 ref 174 174 199 199 199 199 207 207 214 217 
?18 218 236 238 238 264 272 284 284 295 311 311 
311 311 311 31 t 329 334 335 337 338 356 358 358 
363 363 366 368 377 377 379 380 383 383 390 395 
441 468 478 478 480 517 517 518 531 563 566 567 
568 

del 9 set ref 10?* 108 109 
unaligned del 10 set ref 334* 335 337 
del 11 set ref 333* 335 337 338 356 363 368 
unaligned del 12 set ref 174 174 174 174 199 199 199 
199 207 207 207 207 214 217 218 236 238 272 284 
284 329 334 335 337 338 356 363 368 395 468 563 
566 567 568 
unaligned del 13 set ref 351* 354* 373* 381 
del 84 ref 135 

del 14 set ref 102* 103 104* 108* 109* 110* 112 113* 
118 119* 125* 126 127* 139* 14J 143* 149* 150 151* 
174* 176 177* 207* 209 210* 311* 312 313* 383* 384 
385* 496* 497 498* 503* 504 504* 506 507* 551* 552 
552* 

external del 64 ref 104 113 119 127 143 151 177 210 

313 385 498 507 552 
unaligned del 15 set ref 199 199 199 199 214 217 218 

236 238 272 284 284 329* 334 335 337 338 356 363 

368 395* 468* 563 566 567 568 
del 17 set ref 174* 180 199 199 199 199 207* 214 214 

217 218 236 238 272 284 284 326 327* 327 329 329 

334 335 337 338 356 363 368 394* 394 395 395 467* 

467 468 468 563 566 567 568 
del 18 set ref 160* 165* 166 166 248 249 252 254 254 

256 257 276 278 288 289 440 446 482 484 488 527 

528 530 541* 
external del 65 ref 102 
external del 66 ref 117 
external del 67 ref 580 

unaligned del 20 set ref 125* 139* 143* 143* 496* 

498* 498* 507* 507* 
del 85 ref 165 504 504 

H C 1 19 set ref 181* 236 238 272 273* 273 284 284 333 
334 339* 339 563 565* 565 566 567 568 569* 569 

unaligned del 21 set ref 125* 139* 143* 143* 162* 
496* 498* 498* 507* 507* 

del 91 ref 109 

del 92 ref 141 

del 93 p*f no 

external del 68 ref 125 

del 22 set ref 538* 540 

del ?3 set ref 155* 166 249 254 264 265 284 286 288 
291 295 427 438 441 443 485 528 531 538 539* 
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* rom_seo 

oet.^e'f .segments, 
ol obs* 

^cs. 15 set_br_seo 
hcs_ r t^r^i nate_nor,a-r 
hcs_ r t r.jncat e_s 
i 

1 i 

i nrlex 
inHf 



1 03_ 

iox„*CMjt_c'-ers 

i ox_* user mt 
! 



1 enpt n 
1 ins 

l i ne«.c<u f * er 



1 ocate^ 



nul 1 

reverse 
search 



n U*0?2 
oon03u 



basics 

constant 
autnrrat * c 
constant- 
constant 
const ant 
constant 
constant 
automatic 



^0"2^6 automatic 



n 0 1 t J .7 o automatic 



char(l()49576) 
ent ry 

bi t n> 

entry 
ent "-y 
entry 
ent ry 
ent ry 

fixed bin(21,0) 

■fixed D*nt2!,0) 

built in function 
f i xed binf 21 ,0) 



fixed bin(21,0) 



0 (< * 0 3 c constant entry 

r 0^0' j 0 constant entry 

* 0 * C /J constant entry 

^O^a'Ja cnnstan* enfy 

^OOO^s externa"! static oointer 

OO^O^c external static oointpr 



^M^dl\ automatic 
n 0^<:7c automatic 
*00c7i automatic 

c asaa 
f> 0 o <> 7 u automatic 
^J^ioi automatic 



^ 0 0 3 f> c automatic 
f-O^hf'i automatic 



lO^iny automatic 



CO^Gfc constant 
Oy^U^O constant 



fixed bin(21,0) 

fixed bintei ,0) 

fixed b i n f 2 1 , 0 } 
uui 1 t i n f unct i on 

Char 

cban(?l0J 
fixed &in(l7,0) 



fixed bin(l7,0) 
fixed bin(21.,0) 



fixed bin(2t,0) 



builtin function 

entry 

ent r y 

builtin function 
bui 1 t i n f unct i on 



unaligned del 24 set ref 166* 249 254 264 265 284 

266 268 291 295 427 438 441 443 465 528 531 
external del 69 ref 149 
unaligned del 26 set ref 340* 345* 375 
external del 70 ref 139 
external del 72 ref 496 
external del 74 ref 503 
external del 75 ref 590 
external del 76 ref 504 

del 27 set ref 226* 247* 284* 285 286 287 335* 336 
337 338 339 353 356 363 368 370 422* 425 

del 28 set ref 352* 359* 366 368 371* 371 377 379* 
379 389 390 48a* 485 485 485 487 

del 85 ref 249 2*4 286 288 335 337 363 427 528 

del 29 set ref 160* 245 252 256* 262* 265 265 267 
?75 276 284 286 287 289* 290* 293 425* 427 428* 
028 429* 433* 437 440* 441 441 443* 446* 447 484 
a85 488* 527 528 528 530 531 532* 532 542* 

del 30 set ref 160* 254 257* 257 265 267* 267 274 
291 290* 290 422 433* 437* 438 438 440 441 447 478 
480* 480 485 4«7* 487 502 502 503 504 504 507 517 
51«* 518 541 542* 

external del 77 ref 162 172 199 205 307 329 395 468 

external del 78 ref 551 

external del 79 ref 174 207 

external del 80 ref 311 383 

del 90 set ref 174* 207* 551* 

del 90 set ref 311* 383* 

del 31 set ref 245* 248 249 249 260* 260 262 264 
27«* 280 2«0 2«2* 28«* 289 290 337* 338 338* 339 
356 356 358 359 360 368 368 371 372 427* 428 428 

del 32 set ref 249* 251 260 263 264 286* 287 287* 
287 288 288 290 291 291 293 294 295 363* 365 366 
366 368 370 371 372 

del 33 set ref 352* 360* 372* 372 380* 380 383* 

del 85 ref 174 174 199 199 207 207 217 236 272 284 
311 311 33ft 358 377 379 380 478 480 517 518 567 

unaligned del 34 set ref 218* 238* 264* 295* 311 311 
311 311 358 358 363 366 377 377 379 380 390* 441* 
478 47« 480 517 517 518 531* 

unaligned del 35 set ref 218 238 264 295 311 311 3H 
311 35ft 358 363 366 377 377 379 380 390 441 478 
47? 480 517 517 518 531 

del 36 set ref 217* 218 229* 236* 238 253* 263* 264 
264 265 265 267 293* 295 295 306 311 311 311 311 
349 358 35ft 359 360 363 366 377 377 379 380 389* 
390 417* U31* 441 447* 478 478 480 481* 517 517 
518 519* 526* 528* 530 530* 531 531 532 543* 

del 37 set ref 325* 355* 374* 393 

del 38 set ref 2*5* 254 254 254 257 265 265 265 267 

275* 282* 291 291 291 294 352* 363 366 370* 370 

377 377 379 380 
del 39 set ref 226 244 247 276* 278 280* 281* 284 

296* 317* 317 318 341* 392 401* 401 426* 426* 429 

432* 449* 580* 581 581* 
del 85 ref 133 134 141 161 495 551 551 590 
external del 81 ref 143 143 498 498 507 507 
external del 82 ref 58<» 
del 85 ref 286 427 
del 85 ref 566 
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sname 

• r»ame_1 th 
sname w ptr 
souree^count 
source_pt r 

source«_seg 
sub8tr 



temp_segs 
tkn 

tHn 

tO_Ptr 

to«.seg 

token.l th 
/er i f y 
<hUeJ th 



based 
00*365 automatic 
000366 automatic 
OO03?0 automatic 
0OO372 automatic 

b-as*a 



00037a 
*Q04*6 



000400 

00047Q 



000556 
^005^7 



automat i c 
automat i c 

aut oa;at i c 

automatic 

based 

automat i c 

automat i c 



char 

fixed bin(21,0) 
doi nter 

fixed bin(24,0) 
coi nt er 

Char(10«8576) 
ouiltin function 



pointer 
charC*) 

ch a *(?l0) 

dot nter 

char(10«8576) 

fixed bin (21,0) 
buHtin function 
fixed binf2l ,0) 



unaligned del 40 set ref 125* 127* 
del 41 set ref 117* 125 125 127 127 
del 42 set ref 117* 125 127 
del 43 set ref 139* 165 

del 44 set ref 133* 139* 141 161 166 495 496* 502 

503* 504* 590 590* 
unaligned del 45 set ref 166 502* 

del 85 set ref 166* 166 199 199 214 238 249 254* 254 
264 265* 265 2*4 284 286 288 291* 291 295 334 335 
337 356* 356 358* 363 363 366* 366 366* 368 377* 
377 390 427 438* 438 441* 441 4<|3 478* 485* 485 
502* 502 517* 528 531 563 566 568 

am a y del 47 set ref 134* 149* 155 156 589* 

unaligned del 49 set ref 184 185 186 187 188 189 190 
191 192 193 194 195 344 345 562* 568* 580* 

unaligned del 48 set ref 356* 358* 366* 368* 377* 
383 383 390 

del 52 set ref 156* 254 265 291 438 478 485 502 517 
539 540* 

unaligned del 50 set ref 254* 265* 291* 438* 478* 

485* 502 517* 
del 56<l set ref 566* 567 567* 568 569 
del 85 ref 563 

del 560 set ref 563* 564 565 



t M ES DECLARED BY FX^t TCTT CONTEXT. 



ackup 


00?u7<j 


const ant 


1 abel 


del 42? r ef 


244 




>ad_syntax 


001775 


constant 


1 aoel 


del 327 ref 


272 336 




>ottom 


ft0?*7i 


constant 


1 abM 


del 416 ref 


194 




rhl 


*021*6 


const ant 


1 aoel 


del 351 ref 


404 




:h2 


*0?203 


const a nt 


1 ab*l 


del 363 ref 


375 




rhange 


001771 


constant 


label 


del 325 ref 


190 




:1 ean.up 


O03433 


constant 


entry 


internal del 


586 ref 


135 152 456 


:opy 


O0?t^0 


constant 


ent ry 


internal del 


477 ref 


299 410 416 423 454 461 


:prt 


0023^5 


const ant 


) apel 


del 381 ref 


361 




:v_num 


0034^6 


constant 


ent ry 


internal del 


578 ref 


346 


lellin 


C013«l 


constant 


1 aoel 


del 224 ref 


191 




>ds 


00^2*0 


constant 


entry 


external del 


1 




■of 


002621 


constant 


1 abel 


del 467 ref 


252 258 


434 527 


ile 


no?6^7 


constant 


1 abel 


del 454 ref 


189 




ini sh 


00261 1 


constant 


1 abel 


del 456 ref 


178 211 


314 386 


et 


003172 


const ant 


ent ry 


internal del 


524 ref 


227 320 403 


et_nu* 


0034O3 


constant 


ent ry 


internal del 


575 ref 


224 243 305 


et_token 


003324 


constant 


ent ry 


internal del 


557 ref 


182 342 577 


npgt 


0012^1 


constant 


1 aoel 


del 207 ref 


219 




nsert 


001357 


constant 


1 aoel 


del 234 ref 


184 




i ne_end 


002601 


constant 


lah*1 


del 447 ref 


443 




ocate 


00!5?1 


constant 


1 abel 


del 272 ref 


186 




_eof 


001432 


constant 


1 abel 


del 252 ref 


248 




exlin 


001373 


constant 


1 abel 


del 243 ref 


188 




ext 


"01020 


constant 


label 


del 174 ref 
463 470 


180 201 


230 239 268 301 318 331 399 


ol ine 


001762 


constant 


1 abel 


del 317 ref 


308 




xarq 


O02114 


const ant 


1 apel 


del 342 ref 


347 




edit 


OOIOO5 


const ant 


1 abel 


del 172 r«f 


214 




1* npUt 


001.2^0 


constant 


1 abel 


del 205 ref 


163 195 


418 


rint 


001.673 


const ant 


1 abel 


del 305 ref 


187 




rintl 


001712 


constant 


1 abel 


del 311 ref 


297 321 


450 


jt 


O03157 


constant 


ent ry 


internal del 


515 ref 


216 234 246 277 319 402 


Metread 


O032/I2 


constant 


ent ry 


internal del 


548 ref 


200 330 397 469 
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ret yr e 
save 
ski pc h 
s w i t r. n 
t on 



"013*0 

ft 027*6 

ft-0?i;?2 
ftQ3t 5 5 



constant 
constant 
const ant 
constant 
constant 
constant 



label 
e^t ry 
I abel 
e^t ry 
1 abel 
1 aoel 



del 236 ref 185 

Internal del 494 ref 455 462 

del 392 ref 349 

Internal del 536 ref 279 300 411 42 
del 410 ref 193 
del 061 set ref 19? 



TriFRF M;F^ 



ru fJ 7 F X T 



Starr 
Length 



itect 



6 a 



5 ynoo I ^e*s 
44* w 1103 
ilO dot 



Static 
«3?4 
0 



n L : lC^ N A '• i t 
»as 

on unit- or 

cooy 

save 

nut 

oet 

swi tch 
reset pps^ 
■set. t oVe" 

qet^ngw 

c 1 ear .go 



line 13 c 



^ T A r k st*p ryp^ 

M ? external procedure 
ti '■' r> n unit 

internal procedure 

nternaj procedure 

n^e^nal procedure 

nternai procedure 

nte^nai procedure 

n fc e r nal Dnocedure 

internal procedure 

i p r e r» n s j p r o e e u p e 

6 ft internal procedure 



v»H v MrjNQIJlCK/WHO SHARES STACK FRAME 
is an external procedure. 



shares 
shares 
shares 
shares 
shares 
snares 
shares 

S n rt r P S 

is cap 



stack 
stack 
stack 
stack 
st acK 
stack 
stack 
stask 
ed by 



frame of 

frame o* 

frame of 

frame o f 

frame o* 

frame o* 

frame o f 

frame o* 
several 



external 
external 
external 
external 
external 
external 
external 
sxternsl 
noniui ck 



procedure 
procedure 
procedure 
procedure 
procedure 
procedure 
procedure 
procedure 
procedures. 



eds. 
eds. 
eds. 
eds, 
eds. 
eds, 
eds, 
eds. 



s t n & ^.-F 



i or 






■ l n 0 1 u n 


a ro.count 


eds 


i; " 0 10 1 


n r<=>a^ 


eos 


0 Q 1 0 ? 


Kpt-l 


egs 




K u * f «*r 


*»os 


u^i)170 


rhannftS_occu f, rej 


eos 


U^O 1 "/ 1 


code 


eds 


1 7? 


coun* 


ed* 


U * 0 1 7 3 


cs i ze 


eds 


00017'! 


»dr t 


eds 


1^017^ 


d i r_r a m e 


eas 


u^ij?^7 


ant rv w na*e 


eds 


v * i) ? b " 


exrtr 


eds 


Oftf.i^tj? 


* r nrf:_p t r 


eas 


y 0 0 * O '< 


r l n sr. s v 


eas 


0 '*) i > o e s 


i 


*ds 


0 1 u ? 6 A 




eos 




i ndf 


eas 


010*70 


i n*t 


eds 


[)ftj?71 


i 


eas 


000-7' 


k 


eos 


J ^ 0 ^ / ^ 


1 


eds 


0 1 G ? / 4 


1 i ne_bu f *e r 


eds 


0*03^1 


1 ine* 


eds 


0^03o? 


1 o c a t e d 


eas 


O0fj36* 




#»ds 


U ft 0^6'! 


n 


eds 


!)1036* 


s n a m p 1 t H 


eds 


C ^ 03 on 


Sna:.'r_n t r 


eds 


000^70 


SOUPCe.COunt 


eds 
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000372 souree_ptr 

000374 temp_segs 

oooaoo t]ln 

000466 tkn 

0*0*7* to_ptr 

000*56 token^lth 

0*0*57 whitest* 



eds 

eds 

oet_t oken 
net _t oken 



TH* FQILOMNC FXT£"nAL aP£ p AT'J*S APfc U^D Rf T M IS PhOG^A**. 

a11oc_cs cal 1 _ext_out_desc cal 1 _ext_out cal 1 _i _t h i s 

enable shr rt en_st ac k ext_entry <nt^entpy 



cal 1 _1 nt.other 
set_cs_ei s 



return 

* ndex_cs_e* s 



THF FOLLOWING FXTt^ivAL ENTPIFS APfc CALLED *Y THIS PROG^A" 



exDand^pat Hneme_ 

hcs.Sset^bc.sea 

tox_$cont rol 

rel ease_temp_segT»ent s„ 



cu_karq_count 
Qet^temp^seg^e^t s_ 
Hcs.s t ermi nate^noname 



THE FOLLOWING FXTE^NAL VAKlAKLFS AP£ UStn THIS Pf*n u «? A M, 
error_tabl ejnoarg error_taM e_*noer»t ry 

tox_$user_output 



c j«.Sa ro_Dt r 
Hcs.^i ni t i ate_eount 
hcs.^t runcate_sea 
i ox^DUt^cHars 



err or_taM pjtoo.irianv.arqs 



ev_dec_ 

hcs_$make_seq 

<oa_ 

pat hnawe. 



1 ox.$usep.1 nput 



LINE L"c 
1 000227 
no 000300 

120 00041.1 
13* 0005M 
151 0007*6 
162 0007*2 
177 001045 
186 001115 
193 001160 
207 0012*1 
218 001335 
230 0Q«3*b 
245 001376 
253 001435 
26? 00146a 
273 001524 
280 001542 
2SA 00161.3 
296 001o65 
307 001676 
31P 00176a 
329 001777 
337 002056 
345 002122 
354 002146 
363 C022 A 3 
373 002304 
383 002347 
393 002425 
403 00246a 
41* 002473 
428 00252a 
437 00254a 



IT'E Lfjr 
102 Q0Q235 
112 0*0303 
125 0 0 0412 
139 000536 
1*2 00073? 
163 0*o77* 
178 00107^ 
1P7 00112? 
1©4 Q0ll6* 
2*9 0*1?7* 
219 001340 
234 003357 
246 0 0 1 a 0 J 
2*4 001436 
263 0*1*66 
27a 00152*5 
2*1 001547 
2*9 001*27 
2°7 001667 
3*6 001711 
319 00176* 
3^0 002025 
333 002076 
3*6 00213? 
355 002150 
365 C02227 
374 002306 
3*4 002366 
3°4 002*27 
404 002465 
4?2 002*7* 
429 002*30 
433 002546 



L T N c L n C 
1.03 OOO2/45 
U3 00*305 
126 00*4*2 

<al 0006*0 
153 000/36 
16* *u*77& 

ieo ooio 7 5 

183 *QU?7 
19- 0C1172 
?1* *0 127^ 

22* 001 3* i 

2i6 001360 
?47 001402 
256 0ul4*3 
?6* *0!47a 
275 001527 
28? OU1550 
?V* 001 6*3 
?99 001670 
311 001712 
32* 001767 
331 *0?G?6 
33^ 002104 
347 00?133 
356 0Q?i*e: 
366 *0?23G 
37* 00?31g 
365 00?37u 
39* 002^31 
*i* *0?a6o 
a23 0024^6 
431 002534 
flap oo?553 



LINE. L DC 
1*** 0002^7 
114 00Q334 
1?7 00 0*4* 
1*3 00061O 
1*5 0*0737 
166 0*1001 
1M 00110* 
1*9 001134 
i«9 0011.77 
211 0*1^2? 
2?6 00134? 
236 001363 
2*8 0014i! 
257 0*145* 
265 001*77 
27d 001*31 
284 0*155? 
2°1 001635 
30C 0*1*71 
312 001733 
321 001770 
333 002027 
3*0 002U1 
349 0O2134 
3*8 002166 
366 002246 
377 00231? 
3*6 002*14 
3°7 0*2457 
411 0*2*67 
424 002477 
432 002*35 
4*1 0*2563 



LINE LHC 
105 000264 
117 000335 
12ft 000476 
144 000662 
156 0007*1 
17? 001005 
18? 001102 
190 001141 
20* 001233 
?14 0013?3 
227 0013*2 
?39 001372 
249 001414 
258 001460 
?67 001514 
?77 001534 
?85 001571 
293 0016*1 
301 001672 
313 001735 
325 001771 
334 002032 
341 002112 
351 002136 
359 002173 
T70 002265 
379 002335 
389 002415 
399 002460 
412 002a70 
425 00?500 
*33 002537 
*43 002571 



LINE LOC 
108 000265 
118 000355 
133 000477 
149 000663 
160 000743 
174 00102* 
184 0OH03 
191 001146 
201 001235 
216 001332 
228 001353 
243 001373 
251 001431 
260 001461 
268 001520 
278 001535 
286 001572 
294 001654 
305 001673 
314 001761 
326 001772 
335 002037 
342 002114 
352 002137 
360 002177 
371 00227? 
380 002341 
390 002417 
401 002*61 
416 002471 
4?6 002503 
434 002541 
445 002575 



LINE LOC 

109 000272 

119 000357 

13* 000501 

150 000704 

161 0007*6 

176 001043 

185 001110 

192 001153 

205 001236 

217 001333 

229 001355 

244 001374 

25? 001432 

261 001462 

272 001521 

279 001541 

287 001606 

295 001660 

306 001674 

317 001762 

327 001775 

336 002055 

344 002115 

353 002143 

361 002202 

372 002277 

381 0023*5 

39? 002422 

402 002463 

417 002472 

427 002507 

436 002542 

446 002577 
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447 noPb^i 

461. 

A?7 002o5u 

«9* 0027=4 

c 1 9 0 0 3 1 c 6 

526 0Q?i73 

536 0032*5 

? <4 ft 0 0 ^ <d « 1 

57 0 0 1? 3 ^ ^ 

==66 003^2 



4fl9 002^0^ 

0^2*17 

002651 
t,*ii o«V7o3 
4<>v 0^30£7 
51a 0^3157 
5?7 

5 7 3 003?26 

cj^a u r >3'*4* 
575 C*3«03 
5*9 0^3^/*^ 



45 n ^0?b n o 
«b3 ocPo?o 
iib^ n 0?6=7 
48° 0u?705 
^C? 0u3Q7 u 
= 17 no3i*U 
= ^ 0 3 i "7 7 
= 3^ *0323u 
=51 *032«3 
=6 = *033=2 

S77 *0 3-4*<4 

= 5<*5 0Q34*>i; 



4 = 4 002607 
467 002*2! 
491 002*61 
4°4 002706 
503 003036 
518 003166 

5 3 0 0 0 3 ? 1 A 
b«0 Q03?3? 
5S2 003?75 
5^6 0033S3 
57fc 0*340= 
5^2 003501 



455 002610 
469 002623 
482 002662 
495 002707 
504 003054 
519 003170 
= 31 003220 
541 003234 
553 003323 
5t>7 003372 
560 003U07 



456 002611 
469 002646 
484 002665 
496 002713 
506 003075 
520 003171 
532 003223 
542 003236 
557 003324 
568 003376 
5*1 003426 



457 002615 
470 002647 
485 002667 
497 002752 
507 003077 
524 003172 
533 003224 
543 003240 
562 003325 
569 003401 
582 003431 
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APPENDIX C 
MULTICS SUBSYSTEMS 



The Multics system offers many special 4 subsystems , designed to serve a 
particular set of users or perform a particular set of tasks. Some of these 
subsystems are already familiar to you — the Qedx and Emacs text editor systems, 
the input/output system. Various other subsystems are described briefly here. 
For detailed information on any of them, see individual manuals. 



DATA BASE MANAGER 



The Multics Data Base Manager (MDBM) supports the description and processing 
of data bases of widely varying sizes and organizations, and provides a large 
measure of data independence. It consists of an integrated set of functions 
which offer a full range of data base retrieval and update capabilities, and it 
is written to interface with any programming language that supports a call statement. 
The MDBM offers a powerful, extremely flexible method of structuring and manipulating 
data bases: the Multics Relational Data Store (MRDS). 



MRDS supports the relational model of data base organization, in which data 
relationships are represented by means of formal algebraic entities. It allows 
you to structure and access data without concern for how or where it is actually 
stored. A special MDBM query language called LINUS (described later in this 
section) provides comprehensive query capabilities for MRDS data base users. 



Data bases reside within the Multics storage system and are protected by 
all of the security features inherent in the Multics virtual memory environment. 



FAST 



The Multics FAST subsystem is a simple-to-use, low-cost user interface for 
creating and running BASIC and FORTRAN programs. The Multics FAST command language 
is a subset of Multics commands with additional commands for manipulating 
line-numbered text. 



GCOS ENVIRONMENT SIMULATOR 



The GCOS environment simulator, together with several Multics facilities, 
permits GCOS batch-processing jobs to be run under the control of Multics and 
provides some job-scheduling facilities. Invoked via the Multics gcos command, 
the simulator immediately runs one GCOS job in your process. Your terminal is 
treated as if it were the GCOS operator's console. 



C-1 



AG90-03 



It f s also possible to simulate GCOS time-sharing usage, by invoking the 
Multics gcos__tss (gtss) command. 



GRAPHICS 



The Multics Graphics System provides a general purpose interface through 
which user or application programs can create, edit, store, display, and animate 
graphic material. It is a terminal-independent system, which means that a program 
written for one type of graphic terminal is operable without modification on 
another terminal having similar capabilities. 



LOGICAL INQUIRY AND UPDATE 



The Logical Inquiry and Update System (LINUS) is a facility for accessing 
MRDS data bases. The complete data base management capability provided by LINUS 
includes both retrieval and update operations. 



LINUS makes use of a high-level nonprocedural language called LILA (LINUS 
Language) that can be understood by individuals who aren't necessarily computer 
specialists . 



REPORT PROGRAM GENERATOR 



The Multics Report Program Generator (MRPG) is a language translator used 
to generate a PL/I source program from an MRPG source program, with the purpose 
of generating formatted reports. 



SORT/MERGE 



The Sort/Merge subsystem provides generalized file sorting and merging 
capabilities, specialized for execution by user-supplied parameters. Sort orders 
an unranked file according to the values of one or more specified key fields in 
the records you are using. Merge collates the contents of up to ten ordered 
files according to the value of one or more key fields. Input and output files 
associated with the Sort/Merge subsystem can have any file organization and be 
on any storage medium. Records can be either fixed or variable length. 



WORDPRO 



The Multics word processing system, WORDPRO, consists of a set of commands 
that assist you in the input, update, and maintenance of documents. The commands 
provide tools for text editing and formatting, Speedtype, dictionaries for 
hyphenation and spelling, list processing, and electronic mail. 



An important part of the WORDPRO system is the compose command, which is 
used for formatting manuscripts, and has programmable requests that make it a 
minor programming language. 
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APPENDIX D 



THE EDM EDITOR 



The Edm editor is a simple Multics context editor which is used for 
creating and editing ASCII segments. Edm is less sophisticated than Qedx, and 
far less sophisticated than Emacs, so if you are already comfortable with one of 
these editors, this appendix will not be very useful to you. However, if you 
would like to learn how to use a simpler editor, this appendix will help. 



To invoke the Edm editor, you type: 
edm pathname 

when pathname identifies the segment to be either edited or created. 



The Edm editor operates in one of two principal modes: edit or input. If 
pathname identifies a segment that is already in existence, Edm begins in edit 
mode. If pathname identifies a segment that does not exist, or if pathname is 
not given, Edm begins in input mode. You can change from one mode to the other 
by issuing the mode change character: a period (followed by a carriage return) 
which is the only character on a line. For verification, Edm announces its mode 
by responding "Edit." or "Input." when the mode is entered. 



The Edm requests assume that the segment consists of a series of lines and 
has a conceptual pointer to indicate the current line. (The "top" and "bottom" 
lines of the segment are also meaningful.) Some requests explicitly or 
implicitly cause the pointer to be moved; other requests manipulate the line 
currently pointed to. Most requests are indicated by a single character, 
generally the first letter of the name of the request. 



Various Edm requests and their functions are listed below. Detailed 
descriptions of these requests are given later in this section. This list does 
not include all of the Edm requests; it identifies only those requests that you 
will need as you begin using this editor. For a complete listing and 
description of all the Edm requests, see the MPM Commands. 



REQUESTS 



backup 



print current line number 



comment mode 



mode change 



b 



bottom 



d 



delete 
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f find 

i insert 

k kill 

1 locate 

n next 

p print 

q quit 

r retype 

s substitute 

t top 

v verbose 

w write 



GUIDELINES 



The following list offers helpful suggestions about the use of Edm. 

1. It is useful to remember that the editor makes all changes on a copy 
of the segment, not on the original. Only when you issue a w (write) 
request does the editor overwrite the original segment with the edited 
version. If you type a q (quit) without a preceding w, the editor 
warns you that editing will be lost and the original segment will be 
unchanged, and gives you the option of aborting the request. 

2. You should not issue a QUIT signal (press ATTN, BRK, INTERRUPT, etc.) 
while in the editor unless you are prepared to lose all of the work 
you have done since the last w request. However, if a QUIT signal is 
issued, you may return to Edm request level without losing your work 
by issuing the pr ogram_interrupt command. 

3. If you have a lot of typing or editing to do, it is wisest to 
occasionally issue the w request to ensure that all the work up to 
that time is permanently recorded. Then, if some problem should occur 
(with the system, the telephone line, or the terminal), you only lose 
the work done since your last w request. 

4. You should be sure that you have switched from input mode to edit mode 
before typing editing requests, including the w and q requests. If 
you forget, the editing requests are stored in the segment, instead of 
being acted upon. You then have to locate and delete them. 

5. As you become more familiar with the use of Edm, you may conclude that 
it provides verification responses more often than necessary, thus 
slowing you down. You may use the k (kill) request to "kill" the 
verification response. However, once you feel confident enough to use 
the k request, you are probably ready to begin using the more 
sophisticated editor, Qedx. The Qedx editor provides you with a 
repertoire of more concise and powerful requests, permitting more 
rapid work. 
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REQUEST DESCRIPTIONS 



The following Edm requests are the ones that you will find most useful as 
you begin working with this editor. Examples are included to help you see the 
practical use of each request. 



Backup (-) Request 

The backup request moves the pointer backward (toward the top of the 
segment) the number of lines specified, and prints the line to show the location 
of the pointer. For example, if the pointer is currently at the bottom line of 
the following: 

get list (n1 , n2) ; 
sum = n1 + n2; 
put skip; 

put list ("The sum is: Tf , sum); 
and you want the pointer at the line beginning with the word "sum," you type: 

! -2 

sum = n1 + n2; 

If you don't specify a number of lines with the backup request, the pointer 
is moved up one line. (Typing a space between the backup request and the 
integer is optional.) 



Print Current Line Number (= ) Request 

The print current line number request tells you the number of the line the 
pointer is currently pointing to (all the lines in a segment are implicitly 
numbered by the system — 1, 2, 3»..., n). 

Whenever you want to check the implicit line number of the current line, 
you issue this request and Edm responds with a line number. 

I - 

143 



Comment Mode ( , ) Request 

When you invoke the comment mode request, Edm starts printing at the 
current line and continues printing all the lines in the segment in comment mode 
until it reaches the end of the segment, or until you type the mode change 
character (a period) as the only entry on a line. 

To print the lines in comment mode means that Edm prints a line without the 
carriage return, switches to input mode, and waits for your comment entry for 
that line. When you give your comment line and a carriage return, Edm repeats 
the process with the next line. 

If you have no comment for a particular line, you type only a carriage 
return and Edm prints the next line in comment mode. When you want to leave 
comment mode and return to edit mode, you type — as your comment — the mode change 
character (a period). 
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Programmers will find that the comment mode request gives them a fast and 
easy way to put comments in their programs. 



Mode Change ( . ) Request 



The mode change request allows you to go from input mode to edit mode or 
vice versa simply by typing a period as the only character on a line. This 
request is also the means by which you leave the comment mode request and return 
to edit mode. 



For example, when you finish typing information into a segment, you must 
leave input mode and go to edit mode in order to issue the write (w) request and 
save the information. 

! last line of segment 
! . 

Edit. 
! w 



Bottom (b) Request 

The bottom request moves the pointer to the end of the segment (actually 
sets the pointer after the last line in the segment) and switches to input mode. 
This request is particularly helpful when you have a lot of information to type 
in input mode; if you see some mistakes in data previously typed, you can switch 
to edit mode, correct the error, then issue the bottom request and continue 
typing your information. 

! red 

! oramge 

! yellow 

! green 

Edit. 
! -2 

oramge 
! s/m/n/ 

orange 
! b 

Input . 
! blue 



Delete (d) Request 



This request deletes the number of lines specified. Deletion begins at the 
current line and continues according to your request. For example, to delete 
the current line plus the next five lines, you type: 

! d6 



If you issue the delete request without specifying a number, only the 
current line is deleted. (That is, you may type either d or d1 to delete the 
current line.) 



After a deletion, the pointer is set to an imaginary line following the 
last deleted line but preceding the next nondeleted line. Thus, a change to 
input mode would take effect before the next nondeleted line. 
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Find (f ) Request 



The find request searches the segment for a line beginning with the 
character string you designate. The search begins at the line following the 
current line and continues, wrapping around the segment from bottom to top, 
until the string is found or until the pointer returns to the current line; 
however, the current line itself is not searched. If the string is not found, 
Edm responds with the following error message: 

Edm: Search failed. 



If the string is found and you are in verbose mode, Edm responds by 
printing the first line it finds that begins with the specified string. 

! f If 

If the string is found and you are in verbose mode, Edm responds by 



When you type the string, you must be careful with the spacing. A single 
space following the find request is not significant; however, further leading 
and embedded spaces are considered part of the specified string and are used in 
the search. 



In the find request, the pointer is either set to the line found in the 
search or remains at the current line if the search fails. Also, if you issue 
the find request without specifying a character string, Edm searches for the 
string requested by the last find or locate (1) request. 



Insert (i) Request 



The insert request allows you to place a new line of information after the 
current line. 



If you invoke the insert request without specifying any new text, a blank 
line is inserted after the current line. If you type text after the insert 
request, you must be careful with the spacing. One space following the insert 
request is not significant, but all other leading and embedded spaces become 
part of the text of the new line. 



For example, if the pointer is at the top line of the following: 
sum = n1 + n2; 

put list ("The sum is:", sum); 

and you issue the following insert request: 

! i put skip; 

the result is: 

sum = n1 + n2; 
put skip; 

put list ("The sum is:", sum); 



If you want to insert a new line at the beginning of the segment, you first 
issue a top (t) request and then an insert request. 
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Kill 00 Request 



The kill request suppresses the Edm responses following the change (c), 
find (f), locate (1), next (n), and substitute (s) requests. To restore 
responses to these requests, you issue the verbose (v) request. 



It is recommended that as a new user 
are thoroughly familiar with Edm. The 
helpful; they offer an immediate check 
results of your requests. 



you not use the kill request until you 
responses given in verbose mode are 
for you by allowing you to see the 



Locate (1) Request 



The locate request searches the segment for a line containing a 
user-specified string. The locate and find (f) requests are used in a similar 
manner and follow the same conventions. (Refer to the find request description 
for details.) With the find request, Edm searches for a line beginning with a 
specified string; with the locate request, Edm searches for a line 
containing -- any where-- the specified string. 



Next (n ) Request 

The next request moves the pointer toward the bottom of the segment the 
number of lines specified. If you invoke the next request without specifying a 
number, the pointer is moved down one line. When you do specify the number of 
lines you want the pointer to move, the pointer is set to the specified line. 
For example, if you type: 

! n4 

the pointer is set to the fourth line after the current line. The Edm editor 
responds, when in verbose mode, by typing you-specif ied line. 



Print (p) Request 

The print request prints the number of lines specified, beginning with the 
current line, and sets the pointer to the last printed line. If you do not 
specify a number of lines, only the current line is printed. 



If you want to see the current line and the next three lines, you type: 

! p4 

current line 

first line after current line 

second 

third 



In Edm, every segment has two imaginary null lines, one before the first 
text line and one after the last text line. When you print the entire segment, 
these lines are identified as "No line" and "EOF" respectively. 



D-6 



AG90-03 



Quit (q) Request 



The quit request is invoked when you want to exit from Edm and return to 
command level. 



For your convenience and protection, Edm prints a warning message if you do 
not issue a write (w) request to save your latest editing changes before you 
issue the quit request. The message reminds you that your changes will be lost 
and asks if you still wish to quit. 

! Q 

Edm: Changes to text since last "w" request will be lost if you quit; 
do you wish to quit? 



If you answer by typing no, you are still in edit mode and can then issue a 
write (w) request to save your work. If you instead answer by typing yes, you 
exit from Edm and return to command level. 



Retype (r ) Request 

The retype request replaces the current line with a different line typed by 

you. 

One space between the retype request and the beginning of the new line is 
not significant; any other leading and embedded spaces become part of the new 
line. To replace the current line with a blank line, you type the retype 
request and a carriage return. 



Substitute (s) Request 

The substitute request allows you to change every occurrence of a 
particular character string with a new character string in the number of lines 
you indicate. If you are in verbose mode (in which Edm prints responses to 
certain requests), Edm responds by printing each changed line. If the original 
character string is not found in the lines you asked Edm to search, Edm 
responds : 

Edm: Substitution failed. 



For example, if the pointer is at the top line of the following: 

get list (n1 , n2) ; 
sum = n1 + n2; 
put skip; 

put list ("The sum is:", sum); 

and you want to search the next three lines and change the word "sum" to 
"total," you type: 

! s4/sum/total/ 
total = n1 + n2; 

put list ("The total is:", total); 
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The four lines searched by the editor are the current line plus the next 
three. (The search always begins at the current line.) If you do not specify 
the number of lines you want searched, Edm only searches the current line. If 
you do not specify an original string, the new string is inserted at the 
beginning of the specified line(s). 



Notice in the example that a slash (/) was used to delimit the strings. 
You may designate as the delimiter any character that does not appear in either 
the original or the new string. 



Top (t) Request 



The top request moves the pointer to an imaginary null line immediately 
above the first text line in the segment. (See the print request description 
concerning imaginary null lines in Edm.) 



An insert (i) request immediately following a top request allows you to put 
a new text line above the "original" first text line of the segment. 



Verbose ( v) Request 



The verbose request causes Edm to print responses to the change (c), find 
(f), locate (1), next (n), and substitute (s) requests. 



Actually, you do not need to issue the verbose request to cause Edm to 
print the responses; when you invoke Edm, the verbose request is in effect. The 
only time you need to issue the verbose request is to cancel a previously issued | 
kill (k) request. 



Write (w) Request 



The write request saves the most recent copy of a segment in a pathname you 
specify. (The pathname can be either absolute or relative.) 



If you do not specify a pathname, the segment is saved under the name used 
in the invocation of the edm command. When saving an edited segment without 
specifying a pathname, the original segment is overwritten (the previous 
contents are discarded) and the edited segment is saved under the original name. 



If you do not specify a pathname and you did not use a pathname when you 
invoked the edm command, an error message is printed and Edm waits for another 
request. If this happens, you should reissue the write request, specifying a 
pathname. 
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INDEX 



MISCELLANEOUS 



-absentee control argument 7-4 

-all control argument 1-1 

-arguments control argument 7-6 

-brief control argument 1-1 

-brief_table control argument 2-5 

-first control argument 6-3 

-link control argument 2-11 

-list control argument 2-3, 6-3, 6-4, 
7-3 

-long_prof ile control argument 6-3 

-map control argument 2-4, 2-5, B-2 

-notify control argument 7-4, 7-6 

-optimize control argument B-2 

-profile control argument 6-1, 6-2, 
6-4 

-sort control argument 6-3 

-table control argument 2-4, 3-6, 5-6, 
5-8 



A 



absentee facility 1-1, 4-12, 7-1, 7-3, 
7-4, 7-5, 7-6, 8-5, 8-9, 8-10 
accepting arguments 7-5 
capabilities 7-5 
control file 7-1, 7-3, 7-5, 7-6 
enter abs request command 7-1, 7-3, 

7- 4,-7-6 

input file 7-1, 7-3, 7-5, 7-6 

job 1-1, 4-12, 7-1, 7-4, 7-5, 7-6, 

8- 5, 8-10 

output file 7-1, 7-5, 7-6 
process 1-4, 7-1 
production runs 7-1 

absin segment 7-1, 7-3, 7-5, 7-6 

absolute pathname A-6, B-5 

absout segment 7-1, 7-5, 7-6 

access 1-5, 2-6, 2-8, 4-5, 8-4, 8-1, 
B-5, C-1 

access control list 1-12, 8-4 

ACL 

see access control list 
add search rules command 8-7 



address space 1-2, 1-10, 2-6, 3-1, 
3-5, 8-4, 8-5, 8-8, B-6 

addressing online storage 1-7, 3-2, 
A-1 

add search paths command 3-7, 8-4, 
~ 8-7 " 

add_search_rules command 3-3, 8-4 

administrative control 1-12, 3-3 

alignment of variables B-2 

ALM programming language 1-10, 2-1, 
2-2, A-4 

apl command 8-5 

APL programming language 2-1, 2-3, 
8-5, A-1 

archive 

component 2-11, 8-2, 8-6 
segment 2-8, 8-2, 8-6 

archive command 2-8, 2-8, 8-2, 8-6 

attach description 4-9, 4-10 

attaching switch 4-2, 4-9, 4-10 

automatic storage 5-5 



B 



background 1-4, 7-1 

backup request 

see Edm editor requests 

basic command 4-10 

BASIC programming language 2-1, 8-5, 
C-1 



batch 1-1, 7-1 

binary 2-2, 2-5, 2-9, 4-7, B-2 

bind command 2-11, 8-5 

binding 

bind command 2-11 

binder 2-11 

bound segment 2-1 1 

bit count 1-9, 8-2, 8-3, A-6 

bottom request 

see Edm editor requests 

builtin functions 
divide B-7 
index B-9 
reverse B-9 
search B-10 
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builtin functions (cont) 
substr B-9 
verify B-10 

bulk data input 4-12 

byte size 1-9 



C 



cards 

bulk data input 4-12 

control 4-12, 7-3 

conversion 4-12 

input 4-12, 7-3 

remote job entry 4-12, 7-3 

change_wdir command 3-2, 8-4 

change_wdir_ subroutine 3-2 

character string 3-2, 7-5, A-5, B-2, 
D-5 

cleanup handler B-5, B-6 
close_file command 4-10, 8-6 
closing switch 4-4, 4-5, 4-9, 4-10 
cobol command 8-5 

COBOL programming language 2-1, 2-6, 
2-7, 2-8, 4-2, 4-4, 4-7, 4-10, 
4-11, 5-1, 8-5, 8-10 

cobol_abs command 7-6, 8-5, 8-9 

command 

level 2-6, 3-6, 4-10, 5-1, 5-3, 5-5, 

5-8, 6-1, D-7 
line 2-3, 6-2, 7-6, 8-4, 8-7, 8-8 
name B-5 

processor 5-3, 5-5, 5-7, B-5 

commands 

add_search_paths 3-7 
add_search_rules 3-3, 8-4 
apl 8-5 

archive 2-8, 2-8, 8-2, 8-6 
basic 4-10 
bind 2-11, 8-5 
change_wdir 3-2, 8-4 
close_file 4-10, 8-6 
cobol 8-5 

cobol_abs 7-6, 8-5, 8-9 

compare_ascii 2-7, 8-2 

compose 8-2, 8-5, C-2 

copy 2-7, 8-2 

copy_cards 4-11, 4-12, 8-6 

copy_file 4-11, 8-2, 8-6 

create_data_segrnent 8-5, A-4 

delete_search paths 8-7 

delete_search_paths 3-7, 8-4 

delete search_rules 3-3, 8-4, 8-7 

discara^output 6-2, 8-7 

display pl1io_error 4-11, 8-6, 8-7 

edm 8-?, D-1 , D-8 

enter abs request 7-1, 7-3, 7-4, 

7-6, "8-10 
exec_com 2-8, 7-5, 7-6, 8-7 
fast 8-5, 8-7 
file_output 4-11, 8-7 
format_cobol_source 2-7, 8-5 
fortran 7-3, 8-5 
fortran_abs 7-6, 8-5, 8-10 
gcos 8-8, C-1 
gcos_tss C-1 

general_ready 2-8, 8-6, 8-8 

get system search rules 8-4, 8-8 

indent 2-7, 8-2 ~ 

initiate 3-2, 3-5, 8-4 

io call 4-2, 4-4, 4-5, 4-10, 8-7 



commands (cont) 

link 2-11, 3-3, 8-2, 8-3 
list 2-11, 8-4, 8-3 
list_external_variables A-3 
list_ref_names 3-5, 8-4 
move 2-7, 8-3 

new_proc 1-4, 3-5, 4-2, 8-4 

pl1 2-4, 2-5, 2-8, 2-9, 2-10, 3-6, 

5-6, 6-1, 8-5 
pl1_abs 7-6, 8-5 

print 2-4, 4-11, 5-6, 7-4, 7-5, 7-6, 

8-4, 8-5, 8-6, 8-7 
print_attach_table 4-11, 8-7 
print_search_paths 3-7, 8-4, 8-8 
print_search_rules 3-2, 8-4, 8-8 
probe 2-7, 5-1, 5-5, 5-6, 5-8, 5-7, 

8-6 

profile 6-1, 6-2, 6-3, 8-6, B-9 
program_interrupt 2-7, 8-8, D-2 
progress 2-5, 8-6, 8-10 
release 2-7, 5-3, 5-5, 5-8, 8-8, 
B-5 

rename 2-7, 8-3 
resolve_linkage error 3-7, 8-8 
revert_output "5-11 
set_search_paths 3-7, 8-4, 8-8 
set_search_rules 3-3, 8-4, 8-8 
start 2-5, 2-7, 3-7, 5-3, 5-5, 8-8 
status 8-3 

stop_cobol_run 4-11, 8-6 
terminal_output 4-11 
terminate 3-5, 8-4, A-2 
terminate_refname 3-5 
terminate_segno 3-5 
terminate_single_refname 3-5 
trace 5-1 , 5-8, 8-6 
trace_stack 5-5, 8-6 
unlink 2-11, 8-3 
where_search_paths 3-7, 8-5, 8-8 
who 7-4, 8-10 

comment mode request 

see Edm editor requests 

compare_ascii command 2-7, 8-2 

compiler 1-10, 1-12, 2-3, 2-4, 2-5, 
2-6, 2-10, 6-1, 8-5, 8-6, 8-10, 
B-1, B-2, B-4, B-3 

compiling 1-1, 2-6, 3-5 

compose command 8-2, 8-5, C-2 

com_err_ B-5 

com_err subroutine A-5, A-6, B-4, 
B-5, B-6 

constant 2-5, B-3 

control arguments 
-absentee 7-4 
-all 1-1 
-arguments 7-6 
-brief 1-1 
-brief_table 2-5 
-first 6-3 
-link 2-11 
-list 2-3, 6-3, 7-3 
-long profile 6-3 
-map "2-3, 2-4, 2-5, B-2 
-notify 7-4, 7-6 
-optimize B-2 
-profile 6-1, 6-2 
-sort 6-3 

-table 2-4, 3-6, 5-6, 5-8 

control cards 4-12, 7-3 

control characters B-3 

controlled security 1-1, 1-12, 2-1, 
C-1 
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controlled sharing 1-1, 1-4, 1-5, 
1-10, 1-12, 2-11, B-3 

copy command 2-7, 8-2 

copy_cards command 4-11, 4-12, 8-6 

copy_file command 4-11, 8-2, 8-6 



see memory 
core image 1-2 

create data segment command 8-5, A-4, 
A-5 

create_data_segment_ subroutine A-4, 
A-5 



cu subroutine B-4 



cu_$arg_count B-4 
cu_$arg_count subroutine B-4 
cu_$arg_ptr B-5 
cu_$arg_ptr subroutine B-5 
cv_dec_ subroutine B-4, B-10 



D 



daemon 1-4, 8-3, 8-5, 8-9 

data base manager subsystem C-1 

debugging 1-1, 2-2, 2-3, 2-4, 2-6, 

3-5, 5-1, 5-5, 5-6, 5-8, 6-1, 7-1, 
8-6 



debugging tools 
see probe 

default 2-3, 4-2, 4-4, 4-5, 4-9, 5-6, 
8-4, 8-7, 8-8, A-2, B-2 

definition section 2-5 



delete request 

see Edm editor requests 

delete_search paths command 3-7, 8-4, 
8-7 

delete search rules command 3-3, 8-4, 
8-7 



designing 2-1 

detaching switch 4-2, 4-5, 4-10 

device independence 4-1 

direct intersegment references A-3 

directory 2-3, 2-4, 2-11, 3-2, 3-3, 

7- 1, 8-3, 8-4, 8-7, 8-8, 8-9, A-6, 
B-4, B-5 

home 3-2, 7-1 

working 2-3, 2-4, 2-11, 3-2, 3-3, 
4-8, 8-4, 8-7, 8-8 

discard_output command 6-2, 8-7 

display pllio error command 4-11, 8-6, 

8- 7 

divide builtin function B-7 



documenting 2-1, 2-7 



dollar sign 3-2, A-4, B-4 

dynamic linking 1-1, 1-10, 2-5, 3-1, 
3-5, 3-7, A-4 
usage 3-5 



E 



editing 1-10, 2-2, 2-5, 8-2, B-3, C-2, 
D-2 

editor 2-2, 2-8, 3-6, 4-4, 7-4, B-3, 
B-5, D-1 
Edm 2-2, 8-2, B-1, D-1 
Emacs 2-2, 8-2 

Qedx 2-2, 2-8, 2-9, 2-10, 3-1, 3-6, 

7-4, 8-2 
Ted 2-2, 8-2 

edm command 8-2, B-1, D-1, D-8 

Edm editor 2-2, 8-2, B-1, D-1 
requests D-1 , D-2 
backup D-3 
bottom D-4 
comment mode D-3 
delete D-4 
find D-5 
insert D-5 
kill D-6 
locate D-6 
mode change D-4 
next D-6 
print D-6 

print current line number D-3 

quit D-7 

retype D-7 

substitute D-7 

top D-8 

verbose D-8 

write D-8 

Emacs editor 2-2, 8-2 

enter abs request command 7-1, 7-3, 
7-4,~7-6, 8-10 

entry point 1-10, 3-2, 3-6, 5-6, A-5, 
B-4, B-6 

entryname 2-2, 2-3, 2-6, 8-5, 8-8, 
A-6 

error handLing 1-4, 1-10, 2-5, 2-6, 
2-7, 3-5, 3-6, 3-7, 4-5, 4-11, 

5- 5, 5-6, 5-7, 8-6, 8-8, A-5, A-6, 
B-2, B-3, B-4, B-5, D-4, D-5, D-8 

error_output switch 4-5, 4-11 

execution 1-2, 1-4, 1-10, 2-1, 2-3, 
2-5, 2-6, 4-12, 5-2, 5-3, 5-6, 

6- 3, 7-1, 7-3, 8-5, 8-6, 8-7, 8-8, 
A-4 

execution point 1-4 

exec_com command 2-8, 7-5, 7-6, 8-7 

expand_pathname_ subroutine A-6, B-5 

external references 1-10, 2-11, 3-1, 
A-4 

external static variables B-4 



F 



fast command 8-5, 8-7 

fast subsystem 8-5, 8-7, C-1 
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fault 1-10, 2-5, 2-11, 3-7, 5-6, 8-6, 
8-8, B-7 

linkage 1-10, 1-11, 2-11, 3-7, 8-6, 
8-8 

page 2-5, B-7 

file 2-2, 2-9, 3-1, 3-3, 4-1, 4-4, 

4- 8, 4-9, 4-11, 7-1, 7-3, 7-4, 
8-2, 8-3, 8-5, 8-7, 8-10, B-5, 
C-2 

sequential 4-4 
stream 4-1, 4-4, 4-9 

file_output command 4-11, 8-7 

find request 

see Edm editor requests 

format_cobol_source command 2-7, 8-5 

fortran command 7-3, 8-5 

FORTRAN programming language 1-1, 2-1, 
2-2, 2-8, 4-2, 4-4, 4-7, 4-10, 

5- 1, 8-5, 8-6, 8-10, A-1 

fortran_abs command 7-6, 8-5, 8-10 



G 



gates B-4 

gcos command 8-8, C-1 

gcos subsystem 8-8, C-1, C-2 

gcos_tss command C-1 

general_ready command 2-8, 8-6, 8-8 

get system search rules command 8-4, 
~ 8-8 ~~ 

get_temp_segments B-6 

get__temp_segments_ subroutine B-6 

graphics subsystem C-2 



H 



hardware 1-5, 1-9, 2-3, 4-1, B-2, B-3 

hcs_ subroutine 3-1, 3-2, B-4 

hcs_$initiate A-6 

hcs $initiate subroutine 3-1, 3-2, 
~ A-6, B-6, B-10 

hcs $initiate count subroutine 3-2, 
" A-6, B-6, B-7 

hcs_$make_entry subroutine 3-2 

hcs_$make_ptr subroutine 3-2, A-5 

hcs_$make_seg subroutine 3-2 

hcs $terminate_noname subroutine A-6, 
B-10 

help request 

see probe requests 

higher level language 2-3, 2-6 

home directory 3-2, 7-1 



I 



I/O 

see input/output processing 

I/O module 4-1, 4-2, 8-6 
vfile_ 4-9, 4-10, 4-11 

I/O switch 4-1, 4-2, 4-4, 4-5, 4-9, 
4-11, 7-1, 8-2, 8-3, 8-5, 8-6, 
8-7, 8-9, B-4, D-4 

indent command 2-7, 8-2 

index builtin function B-9 

info segment 2-8, 3-7, 8-9 

initiate command 3-2, 3-5, 8-4 

initiating segments 1-7, 3-5, A-6 

input/output processing 1-1, 2-2, 2-8, 
2-9, 2-10, 4-5, 4-8, 4-9, 4-10, 
4-11, 4-12, 7-1, 8-2, 8-5, 8-7, 
8-8, B-2, B-3, B-4,. B-5 
modules 4-1, 4-2, 4-5, 8-6 
switches 4-1, 4-2, 4-4, 4-5, 4-9, 
4-11, 7-1, 8-2, 8-3, 8-5, 8-6, 
8-7, 8-9, B-4, D-4 
attaching 4-2, 4-9, 4-10 
closing 4-4, 4-5, 4-9, 4-10 
detaching 4-2, 4-5, 4-10 
error_ouput 4-5 
error_output 4-1 1 
opening 4-2, 4-4, 4-9, 4-10 
user_input 4-5, 4-11 
user_io 4-5, 4-11 
user_output 4-5, 4-11, 8-5, B-7 

insert request 

see Edm editor requests 

interactive 1-1, 1-4, 2-4, 5-8, 7-1, 
8-5, B-1 

internal automatic variables A-2 
internal static variables A-2, B-3 
interpreted language 2-3, 8-5 
intersegment link 2-11 
ioa_ subroutine B-4, B-7 



iox subroutine 4-2, 4-4, 4-5, 4-12, 
~ B-8 

iox_$get_line subroutine B-8 
iox_$user_input B-8 
iox__$user_input subroutine B-8 
io_call command 4-2, 4-4, 4-5, 4-10 



J 



JCL 

see job control language 
job control language 1-1, 1-7, 4-2 
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kill request 

see Edm editor requests 



language 1-1, 2-1, 2-2, 2-3, 2-5, 2-6, 
3-7, 4-2, 8-6, A-1, B-2, B-3, C-1 
higher level 2-3, 2-6 
interpreted 2-3, 8-5 
machine 2-3 
programming 2-2, C-1 

ALM 1-10, 2-1, 2-2, A-4 
A PL 2-1, 2-3, 8-5, A-1 
BASIC 2-1, 8-5, C-1 
COBOL 2-1, 2-6, 2-7, 2-8, 4-2, 
4_4, 4-7, 4-10, 4-11, 5-1, 
8-5, 8-10 
FORTRAN 1-1, 2-1, 2-2, 2-8, 4-2, 

4-4, 4-7, 4-10, 5-1, 8-5, 8-6, 
8-10, A-1 

PL/I 1-1, 2-1, 2-2, 2-5, 2-7, 2-8, 
2-9, 3-6, 4-2, 4-4, 4-10, 
4-11, 5-1, 6-2, 8-5, 8-6, 
8-10, A-1, A-2, B-1, B-2, B-3, 
B-4, B-5, B-6, C-2 
source 2-5, 6-3, 8-6 

library 1-10, 3-2, 3-7, A-1, A-6, B-2, 
B-3, B-4, B-5 

link 

intersegment 2-11 

storage system 2-11, 8-2, 8-3 

link command 2-11, 3-3, 8-2, 8-3 

linkage editor 
see loading 

linkage fault 1-10, 1-11, 2-11, 3-7, 
8-6, 8-8 

linkage section 2-5 

linking 1-10, 2-5, 2-11, 3-1, 3-3, 

3-6, 3-7, 8-2, 8-3, 8-6, 8-8, B-4 

LINUS 

see logical inquiry and update 
subsystem 

list command 3-3, 8-3 

listing segment 2-3, 2-4, 6-3, 7-3, 
B-2 

list_external_variables command A-3 

list_ref_names command 3-5, 8-4 

list_requests request 
see probe requests 

load module 
see loading 

loading 1-10, 2-5 

locate request 

see Edm editor requests 

logical inquiry and update subsystem 
C-2 



machine language 2-3 



making a segment known 1-5, 2-7, 3-1, 
8-4, B-5 

MDBM 

see data base manager subsystem 

memory 1-1, 1-2, 1-7, 1-10, 7-5, 8-6, 
8-8, A-1, B-1, B-3, B-6, C-1 

merge subsystem C-2 

mode change request 

see Edm editor requests 

move command 2-7, 8-3 

MRPG 

see report program generator 
subsystem 



N 

named offsets A-4 

naming conventions 2-3 

new_proc command 1-4, 3-5, 4-2, 8-4 

next request 

see Edm editor requests 

null string A-5 



object map 2-5 

object name 2-4 

object program 

see object segment 

object segment 2-3, 2-5, 2-6, 2-7, 
2-11, 3-6, 5-6, 8-5, A-4, B-3 
section 

definition 2-5 
linkage 2-5 
object map 2-5 
static 2-5, A-2 
symbol 2-5 
text 2-5 

online 2-4, 2-8, 7-1, 8-1, 8-6, A-1 
opening modes 4-4 

opening switch 4-2, 4-4, 4-9, 4-10 
options (constant) B-3 
options (variable) B-2 
overlay defining B-3 



page 1-9, 2-5, 8-6, 8-10, B-7 
page fault 2-5, B-7 

pathname 3-6, 8-4, A-6, B-5, D-1 , D-8 
absolute A-6, B-5 
relative A-6, B-5 

pathname^ B-6 

pathname^ subroutine B-6 
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performance measurement tools 
see profile facility 

PL/I programming language 1-1, 2-1, 

2- 2, 2-5, 2-7, 2-8, 2-9, 3-6, 4-2, 

4- 4, 4-10, 4-11, 5-1, 6-2, 8-2, 
8-5, 8-6, 8-10, A-1, A-2, B-1 , 
B-2, B-3, B-4, B-5, B-6, C-2 

pl1 command 2-4, 2-5, 2-8, 2-9, 2-10, 

3- 6, 5-6, 6-1, 8-5 

pl1_abs command 7-6, 8-5 

position request 
see probe requests 

precision of variables B-2, B-3 

print command 2-4, 4-11, 5-5, 5-6, 

7- 4, 7-5, 7-6, 8-4, 8-5, 8-6, 8-7 

print current line number request 
see Edm editor requests 

print request 

see Edm editor requests 

print_attach_table command 4-11, 8-7 

print search paths command 3-7, 8-4, 
o~-8 

print search rules command 3-2, 8-4, 
"5-8 

probe 2-7, 5-1, 5-5, 5-6, 5-8 
requests 
help 5-8 
list requests 5-8 
position 5-7 
quit 5-8 
source 5-7 
stack 5-7 
symbol 5-7 
value 5-7 

probe command 2-7, 5-1, 5-5, 5-6, 5-8, 

8- 6 

process 1-12, 3-2, 3-5, 4-5, 5-1, 7-1, 

8-1, 8-4, 8-6, 8-7, 8-8, 8-9, B-2, 
B-3 

processor 1-2, 1-10, 1-12, 5-1, 5-3, 

5- 5, B-5 

production run 7-1 

profile command 6-1, 6-2, 6-3, 8-6, 
B-9 

profile facility 6-1, 6-3 

programming 1-12, 2-1, 2-2, 7-1, B-1, 
C-1 

programming environment 1-2, 1-4, 
1-12, 2-1, 2-8, 4-8, 5-1, 5-5, 
7-1, 8-8, C-1 

programming language 2-2, C-1 

program_interrup command 8-8 

program_interrupt command 2-7, D-2 

progress command 2-5, 8-6, 8-10 

pure procedure 2-6, B-3 



Q 



Qedx editor 2-2, 2-8, 2-9, 2-10, 3-1, 
3-6, 7-4, 8-2 

quit request 

see Edm editor requests 
see probe requests 

QUIT signal 2-5, 2-6, 5-2, 5-5, B-5, 
D-2 



R 



ready message 2-5, 2-6, 2-8, 3-6, 6-3, 
8-6, 8-8 

record 1-5, 4-1, 4-11, 4-12, 5-1, 6-3, 
8-2, B-2, B-5, C-2 

recursive procedure 2-6 

reference name 3-1, 3-2, 3-3, A-6, 
B-6 



reference to named offsets A-4 



references 

external 1-10, 2-11, 3-1, A-4 

relative pathname A-6, B-5 

release command 2-7, 5-3, 5-5, 5-8, 
8-8, B-5 

release_temp_segments B-6 

release temp segments subroutine B-6, 
B-T0 

remote job entry 4-12, 7-3 

rename command 2-7, 8-3 

report program generator subsystem 
C-2 

resolve linkage error command 3-7, 
8-3 

restarting suspended programs 2-7, 
3-7, 5-5 

retype request 

see Edm editor requests 

reverse builtin function B-9 

revert_output command 4-11 

ring structure B-4 



S 



search builtin function B-10 

search paths 8-4, 8-7, 8-8 

search rules 3-1, 3-2, 3-3, 3-7, 8-4, 
8-7, 8-8 

segment 

absin 7-1, 7-3, 7-5, 7-6 

absout 7-1, 7-5, 7-6 

archive 2-8, 8-2, 8-6 

bound 2-11 

info 2-8, 3-7, 8-9 

listing 2-3, 2-4, 6-3, 7-3, B-2 

number 1-7, 2-7, 3-3, B-6 
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segment (cont) 

object 2-3, 2-5, 2-6, 2-7, 2-11, 

3-6, 5-6, 8-5, A-4, B-3 
size of B-3 

source 2-2, 2-3, 2-7, 8-2, 8-5, B-2, 

C-2 
stack 5-1 

structured data A-5 

segment number 1-7, 2-7, 3-3, B-6 

segments 

temporary B-3 

sequential file 4-4 

set search paths command 3-7, 8-4, 
" 8-8 ~ 

set search rules command 3-3, 8-4, 
" 8-8 ~ 

snapping a link 1-10, 1-11, 2-11, 3-5, 
A-4 

sort subsystem C-2 

source language 2-5, 6-3, 8-6 

source program 

see source segment 

source request 

see probe requests 

source segment 2-2, 2-3, 2-7, 8-2, 
B-2, C-2 

stack 5-1, 5-2, 5-3, 5-5, 5-7, 8-6, 
B-5 

frame 5-2, 5-5, B-5 

stack request 

see probe requests 

standard format 2-6 

start command 2-5, 2-7, 3-7, 5-3, 5-5, 
8-8 

start_up.ec 2-8, 7-1 

static section 2-5, A-2 

static storage 5-5 

status command 8-3 

stop_cobol_run command 4-11, 8-6 

storage 1-7, 1-12, 2-1, 2-11, 4-8, 

5-5, 8-3, 8-6, 8-7, 8-9, A-1 , A-2, 

B-1, B-2, B-3, B-5, C-1 

automatic 5-5 

static 5-5 

storage system link 2-11, 8-2, 8-3 

stream file 4-1, 4-4, 4-9 

structured data segment A-5 

subroutines 

change_wdir_ 3-2 

com_err_ A-5, A-6, B r 4, B-5, B-6 

create data segment A-4 

cu_ B-4 

cv_dec_ B-4, B-10 
expand pathname_ A-6, B-5 
hcs_ 3-1, 3-2, B-4 
hcs_$initiate 3-1, 3-2, B-6, B-10 
hcs_$initiate_count 3-2, A-6, B-6, 
B-7 

hcs_$make_entry 3-2 
hcs_$make_ptr 3-2, A-5 



subroutines (cont) 
hcs_$make_seg 3-2 
hcs_$terminate_noname A-6, B-10 
ioa B-4, B-7 

iox~ 4-2, 4-4, 4-5, 4-12, B-8 
iox_$get_line B-8 

substitute request 

see Edm editor requests 

substr builtin function B-9 

subsystem 

data base manager C-1 
fast 8-5, 8-7, C-1 
gcos 8-8, C-1, C-2 
graphics C-2 

logical inquiry and update C-2 
merge C-2 

report program generator C-2 
sort C-2 
wordpro C-2 

suffix 2-2, 2-3, 2-4, 6-3, 7-1, 7-5 

symbol request 

see probe requests 

symbol section 2-5 

symbol table 2-4, 2-5, 5-6, 5-7 

system 1-1, 1-12, 2-1, 2-11, 3-2, 3-3, 

4-1, 4-4, 5-5, 5-7, 7-4, 8-2, 8-6, 

8-7, 8-8, 8-1, A-5, B-1, B-3, B-4, 
C-1 



T 



Ted editor 2-2, 8-2 

temporary segment B-5 

terminal 

session 1-1, 2-8, 2-9, 8-5 

using for I/O 2-2, 2-6, 2-8, 2-9, 

4-5, 7-1, 8-7, 8-8, B-4, B-5 

terminal_output command 4-11 

terminate command 3-5, 8-4, A-2 

terminate_refname command 3-5 

terminate_segno command 3-5 

terminate_single_refname command 3-5 

terminating segments 1-7, 3-3, A-2, 
A-6, B-5 

text section 2-5 

top request 

see Edm editor requests 

trace command 5-1, 5-8, 8-6 

trace_stack command 5-5, 8-6 



U 



unlink command 2-11, 8-3 

user_input switch 4-5, 4-11 

user_io switch 4-5, 4-11 

user output switch 4-5, 4-11, 8-5, 
~B-7 



i-7 



AG90-03 



V 



value request 

see probe requests 

variables 

alignment B-2 
external static A-3, B-4 
internal automatic A-2 
internal static A-2, B-3 
precision B-2, B-3, B-7 

verbose request 

see Edm editor requests 

verify builtin function B-10 

vfile_ I/O module 4-9, 4-10, 4-11 

virtual memory 1-4, 1-5, 1-7, 1-10, 
B-1, B-3, B-6, C-1 



W 



where search paths command 3-7, 8-5, 
3-8 



who command 7-4 



word 1-9 



wordpro subsystem C-2 

working directory 2-3, 2-4, 2-11, 3-2, 
3-3, 8-4, 8-7, 8-8 

write request 

see Edm editor requests 

writing 2-1, A-1, B-2 
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